દસ્તાવેજીકરણ ટિપ્પણીઓ

ઘણીબધા વાક્યની ટિપ્પણીઓ કે જે વધારાનાં '*' ચિહ્ન દસ્તાવેજીકરણ બ્લોક સાથે શરૂ થાય છે કે જે GTK-Doc સાધનો દ્દારા પ્રક્રિયા થયેલ હશે.

ઉદાહરણ 3-2GTK-Doc ટિપ્પણી બ્લોક
/**
 * identifier:
 * documentation ...
 */

          

The 'identifier' is one line with the name of the item the comment is related to. The syntax differs a little depending on the item. (TODO add table showing identifiers)

The 'documentation' block is also different for each symbol type. Symbol types that get parameters such as functions or macros have the parameter description first followed by a blank line (just a '*'). Afterwards follows the detailed description. All lines (outside program- listings and CDATA sections) just containing a ' *' (blank-asterisk) are converted to paragraph breaks. If you don't want a paragraph break, change that into ' * ' (blank-asterisk-blank-blank).

When documenting code, describe two apsects:

  • What it is: The name for a class or function can sometimes be misleading for people coming from a different background.
  • What it does: Tell about common uses. Put it in releation with the other API.

One advantage of hyper-text over plain-text is the ability to have links in the document. Writing the correct markup for a link can be tedious though. GTK-Doc comes to help by providing several useful abbreviations.

  • વિધેયો અથવા મેક્રોનો સંદર્ભ લેવા માટે function() ને વાપરો કે જે દલીલોને લે છે.
  • પરિમાણોનો સંદર્ભ લેવા માટે @param ને વાપરો. બીજા વિધેયોનાં પરિમાણો માટે જ્યારે સંદર્ભ કરી રહ્યા હોય ત્યારે આને પણ વાપરો, વર્ણવવા માટે એકને સંબંધિત છે.
  • કૉન્સ્ટન્ટ નો સંદર્ભ લેવા માટે %constant ને વાપરો, દા.ત. %G_TRAVERSE_LEAFS.
  • સંકેતનાં બીજા પ્રકારોનો સંદર્ભ લેવા માટે #symbol ને વાપરો, દા.ત. structs અને enums અને macros કે જે દલીલો લેતુ નથી.
  • #Object ને વાપરો::GObject સંકેતનો સંદર્ભ લેવા માટે સંકેત
  • #Object ને વાપરો:GObject ગુણધર્મનો સંદર્ભ લેવા માટે ગુણધર્મ
  • બંધારણની અંદર ક્ષેત્રનો સંદર્ભ લેવા માટે #Struct.field ને વાપરો.

જો તમારે તેઓને બદલ્યા વગર GTK-Doc વગર તમારાં દસ્તાવેજીકરણમાં વિશિષ્ટ અક્ષરો '<', '>', '()', '@', '%', or '#' ને વાપરવાનું ઇચ્છતા હોય તો તમે XML વસ્તુઓ "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" અને "&num;" ને વાપરી શકો છો અથવા બેકસ્લેશ '\' સાથે તેઓમાંથી બહાર નીકળી જાઓ.

DocBook can do more than just links. One can also have lists, tables and examples. To enable the usage of docbook SGML/XML tags inside doc-comments you need to have --xml-mode or --sgml-mode in the variable MKDB_OPTIONS inside Makefile.am.

Since GTK-Doc-1.18 the tool supports a subset or the markdown language. One can use it for sub-headings and simple itemized lists. On older GTK-Doc versions the content will be rendered as it (the list items will appear in one line separated by dashes).

ઉદાહરણ 3-3GTK-Doc comment block using markdown
/**
 * identifier:
 *
 * documentation ...
 *
 * # Sub heading #
 *
 * more documentation:
 * - list item 1
 * - list item 2
 *
 * Even more docs.
 */

          

પહેલાનાં GTK-Doc માં પહેલેથી જણાવેલ પ્રમાણે સાર્વજનિક API દસ્તાવેજીકરણ માટે છે. છતાં એક એ સ્થિર સંકેતો માટે દસ્તાવેજીકરણ ને લખી શકતુ નથી. તેમ છતાં તે પેલાં સંકેતો પર ટિપ્પણી કરવા માટે સારુ છે. આ તમારાં કોડને સમજવા માટે બીજાને મદદ કરે છે. માટે આપણે સામાન્ય ટિપ્પણીઓની મદદથી આ ટિપ્પણી એ અગ્રહણીય કરેલ છે (પહેલાં વાક્યમાં બીજા '*' વગર). જો પછી વિધેયને સાર્વજનિક બનાવવાની જરૂર છે, ટિપ્પણી બ્લોકમાં બીજા '*' ઉમેરવા માટે બધાને કરવાની જરૂર છે અને ફાઇલ વિભાગોની અંદર જમણી જગ્યા પર સંકેત નામને દાખલ કરો.