చిహ్నముల పత్రికీకరణ

Each symbol (function, macro, struct, enum, signal and property) is documented in a separate block. The block is best placed close to the definition of the symbols so that it is easy to keep them in sync. Thus functions are usually documented in the c-source and macros, structs and enums in the header file.

3.3.1. సాధారణ టాగ్లు

మీరు వర్షనింగ్ సమాచారమును అన్ని పత్రికీకరణ మూలకాలకు జతచేయవచ్చును, api యెప్పుడు పరిచయం చేయబడిందో చెప్పుటకు, లేదా యెప్పుడు తీసివేయబడిందో చెప్పుటకు.

వర్షనింగ్ టాగ్స్
అప్పటినుంచి:

కోడ్ యొక్క యే వర్షన్ నుండి API అందుబాటులోవుందో వివరణ.

తీసివేసిన:

ఈ ఫంక్షన్ యికపై వుపయోగించుటలేదని పారాగ్రాఫ్ చెబుచున్నది. వివరణ చదువరిని కొత్త APIకు సూచించాలి.

(FIXME : స్థిరత్వ సమాచారము)

ఉదాహరణ 3-5సాధారణ టాగ్లు
/**
 * foo_get_bar:
 * @foo: some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: @foo's bar
 *
 * Since: 2.6
 * Deprecated: 2.12: Use foo_baz_get_bar() instead.
 **/
Bar *
foo_get_bar(Foo *foo)
{
...

          

3.3.2. ఫంక్షన్ వ్యాఖ్యానపు బ్లాక్

దయచేసి దీనికి గుర్తువుంచండి:

  • తిరిగివచ్చిన objects, lists, strings, మొదలగునవి, freed/unrefed/released చేయాలా వద్దా అనేదానిపై పత్రము.
  • పారామితులు NULL కావచ్చా, వొకవేళ అయితే యేమి జరుగును అనేదానిపై పత్రము.
  • తగుచోట్ల ఆసక్తికరమైన ప్రి-కండీషన్లు మరియు పోస్ట్-కండీషన్లను తెలుపుము.

Gtk-doc అన్ని చిహ్నములు (macros, functions) '_'తో ప్రారంభమగునవి వ్యక్తిగతమైనవని పరిగణించును. అవి స్టాటిక్ ఫంక్షన్సు వలె పరిగణించబడును.

gobject యింట్రోస్పెక్షన్ యెన్నోయేషన్ టాగ్స్ వద్ద కూడా చూడండి: http://live.gnome.org/GObjectIntrospection/Annotations

ఉదాహరణ 3-6ఫంక్షన్ వ్యాఖ్యానపు బ్లాక్
/**
 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 * @...: a %NULL-terminated list of bars
 *
 * The function description goes here. You can use @par1 to refer to parameters
 * so that they are highlighted in the output. You can also use %constant
 * for constants, function_name2() for functions and #GtkWidget for links to
 * other declarations (which may be documented elsewhere).
 *
 * Returns: an integer.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use other_function() instead.
 */

          
ఫంక్షన్ టాగ్లు
తిరిగివచ్చినవి:

పారాగ్రాఫ్ తిరిగివచ్చిన ఫలితాన్ని వివరిస్తుంది.

@...:

ఒకవేళ ఫంక్షన్ వేరియాడిక్ ఆర్గుమెంట్లను కలిగివుంటే, మీరు ఈ టాగ్‌ను వుపయోగించాలి (@Varargs: చారిత్రక కారణాలకు కూడా పనిచేయును).

3.3.3. లక్షణము వ్యాఖ్యాము బ్లాక్

ఉదాహరణ 3-7లక్షణము వ్యాఖ్యాము బ్లాక్
/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

          

3.3.4. సంకేతపు వ్యాఖ్యానము బ్లాక్

దయచేసి దీనికి గుర్తువుంచండి:

  • సంకేతము యెప్పుడు వెలువడింది మరియు అది సంకేతముల ముందు వెలువడిందా లేదా తర్వాత అనేది పత్రికీకరణ చేయును.
  • సంకేత సంభాలిక నందు వొక అనువర్తనము యేమి చేయవచ్చును అనే పత్రము.

ఉదాహరణ 3-8సంకేతపు వ్యాఖ్యానము బ్లాక్
/**
 * FooWidget::foobarized:
 * @widget: the widget that received the signal
 * @foo: some foo
 * @bar: some bar
 *
 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
 */
foo_signals[FOOBARIZE] =
  g_signal_new ("foobarize",
                ...

          

3.3.5. Struct వ్యాఖ్యానము బ్లాక్

ఉదాహరణ 3-9Struct వ్యాఖ్యానము బ్లాక్
/**
 * FooWidget:
 * @bar: some #gboolean
 *
 * This is the best widget, ever.
 */
typedef struct _FooWidget {
  /*< private >*/
  GtkWidget parent;

  /*< public >*/
  gboolean bar;
} FooWidget;

          

Use /*< private >*/ before the private struct fields you want to hide. Use /*< public >*/ for the reverse behaviour.

Struct comment blocks can also be used for GObjects and GObjectClasses. It is usualy a good idea to add a comment blco for a class, if it has vmethods (as this is how they can be documented). For the GObject itself one can use the related section docs, having a separate block for the instance struct would be useful if the instance has public fields. One disadvantage here is that this creates two index entries of the same name (the structure and the section).

3.3.6. Enum వ్యాఖ్యానము బ్లాక్

ఉదాహరణ 3-10Enum వ్యాఖ్యానము బ్లాక్
/**
 * Something:
 * @SOMETHING_FOO: something foo
 * @SOMETHING_BAR: something bar
 *
 * Enum values used for the thing, to specify the thing.
 *
 **/
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

          

Use /*< private >*/ before the private enum values you want to hide. Use /*< public >*/ for the reverse behaviour.