పత్రికీకరణ వ్యాఖ్యలు

బహుళ వరుసలు వుండి అదనపు '*' గుర్తులతో ప్రారంభించబడు వ్యాఖ్య పత్రికీకరణ బ్లాక్‌ను సూచించును అది GTK-Doc సాధనముల ద్వారా నిర్వర్తించబడును.

ఉదాహరణ 3-2GTK-Doc వ్యాఖ్య బ్లాక్
/**
 * identifier:
 * documentation ...
 */

          

'identifier' అనునది వ్యాఖ్యకు సంభందించిన అంశము యొక్క నామముతో వుండు వొక వరుస. అంశము పై ఆధారపడి సిన్టాక్సు అనునది కొద్దిగా విభేదించును. (చేయవలసినది identifies చూపు పట్టికను జతచేయి)

ప్రతి చిహ్నపు రకమునకు 'పత్రికీకరణ' బ్లాక్ భిన్నంగా వుంటుంది. ఫంక్షన్లు లేదా స్థూలములు పారామితి వివరణను కలిగివున్నవి ముందుగా ఖాళీ వరుస (a '*') అనుసరించాలి. తరువాత విశదీకృత వివరణను అనుసరించాలి. అన్ని వరుసలు (ప్రోగ్రామ్ బయటవి- జాబితాలు మరియు CDATA విభాగములు) ' *' (ఖాళీ-యాస్ట్రిక్) మాత్రమే కలిగివున్నవి పారాగ్రాఫ్ విరామాలుగా వుంచబడును. మీకు పారాగ్రాఫ్ విరామాలు అక్కరలేకపోతే, దానిని ' * ' (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.

సాదా-పాఠ్యమునందు హైపర్-పాఠ్యమును కలిగివుండువలన వొక సౌకర్యము పత్రమునందు లింకులను కలిగివుండవచ్చును. అయినను లింకు కొరకు సరైన మార్కప్ వ్రాయుట చికాకే. GTK-Doc నందు చాలా వుపయోగకర ఎబ్రివేషన్లు అందించబడుచున్నవి.

  • ఆర్గుమెంట్లను తీసుకొనే ఫంక్షన్లను లేదా మాక్రోలను సూచించుటకు function() వుపయోగించుము.
  • పారామితులను సూచించుటకు @param వుపయోగించుము. వివరించబడిన పారామితికి సంభందించిన యితర ఫంక్షన్ల పారామితులను సూచించుటకు కూడా దీనిని వుపయోగించుము.
  • స్థిరరాశిని సూచించుటకు %constant వుపయోగించుము, ఉ.దా. %G_TRAVERSE_LEAFS.
  • ఇతర రకముల చిహ్నమును సూచించుటకు #symbol వుపయోగించుము, ఉ.దా. ఆర్గుమెంట్లు తీసుకొని structs మరియు enums మరియు macros వంటివి.
  • GObject సంకేతమును సూచించుటకు #Object::signal వుపయోగించుము
  • GObject లక్షణమును సూచించుటకు #Object:property వుపయోగించుము
  • స్ట్రక్చర్ నందలి క్షేత్రమును సూచించుటకు #Struct.field వుపయోగించుము.

మీరు ప్రత్యేక ఆక్షరములు '<', '>', '()', '@', '%', or '#'ను మీ పత్రికీకరణనందు GTK-Doc వాటిని మార్చకుండా వుపయోగించాలి అంటే మీరు 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 పత్రికీకరణ కొరకు. స్థిర చిహ్నములకు వొక్కరే పత్రికీకరణ వ్రాయలేరు. ఆ చిహ్నములను కూడా వ్యాఖ్యానించుట మంచిది. ఇది యితరులు కూడా మీ కోడ్‌ను అర్ధము చేసుకొనుటకు సహాయపడును. అందుకని వీటిని సాదారణ వ్యాఖ్యలు (మొదటి వరుసనందు 2వ '*' లేకుండా) వుపయోగించి వ్యాఖ్యానించమని సూచించడమైంది. తరువాత ఆ ఫంక్షన్ పబ్లిక్‌గా మార్చవలసివుంటే, చేయవలసినదల్లా వేరొక '*'ను వ్యాఖ్య బ్లాక్ నందు చేర్చి మరియు చిహ్నపు నామాన్నివిభగాముల ఫైలునందు సరైన స్థానములో వుంచడమే.