ஆவணமாக்க விமரிசனங்கள்
A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the GTK-Doc tools.
/** * identifier: * documentation ... */
'identifier' எனப்படும் இனம் காட்டி விமர்சனம் பொருந்தும் உருப்படியின் பெயருடன் கூடிய ஒரு வரி. உருப்படியை பொருத்து இலக்கணம் சற்று மாறலாம்.
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). This is useful in preformatted text (code listings).
When documenting code, describe two aspects:
- 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 relation 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.
- Use function() to refer to functions or macros which take arguments.
- Use @param to refer to parameters. Also use this when referring to parameters of other functions, related to the one being described.
- Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
- Use #symbol to refer to other types of symbol, e.g. structs and enums and macros which don't take arguments.
- Use #Object::signal to refer to a GObject signal.
- Use #Object:property to refer to a GObject property.
- Use #Struct.field to refer to a field inside a structure.
சிறப்பு குறிகளான '<', '>', '()', '@', '%', அல்லது '#' ஐ ஜிடிகே டாக் மாற்றாமல் அப்படியே ஆவணத்தில் பயன்படுத்த அவற்றுக்கான ஹெச்எம்எல் ஐ பயன்படுத்துக: "<", ">", "(", ")", "@", "%" மற்றும் "#" அல்லது பின் சாய்வு கோடால் அவற்றை தனியாக்கலாம்.'\'.
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).
/** * identifier: * * documentation ... * * # Sub heading # * * more documentation: * - list item 1 * - list item 2 * * Even more docs. */
ஜிடிகே டாக்