સંકેતોનું દસ્તાવેજ કરી રહ્યા છે
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. સામાન્ય ટેગ
- 3.3.2. Annotations
- 3.3.3. વિધેય ટિપ્પણી બ્લોક
- 3.3.4. ગુણધર્મ ટિપ્પણી બ્લોક
- 3.3.5. સંકેત ટિપ્પણા બ્લોક
- 3.3.6. Struct ટિપ્પણી બ્લોક
- 3.3.7. Enum ટિપ્પણી બ્લોક
3.3.1. સામાન્ય ટેગ
You can add versioning information to all documentation elements to tell when an API was introduced, or when it was deprecated.
- જ્યાં સુધી:
-
વર્ણન જ્યાં સુધી API કોડનું કઇ આવૃત્તિ ઉપલ્બધ છે.
- અપ્રચલિત થયેલ:
-
ફકરાને સૂચિત કરી રહ્યા છે કે જે આ વિધેયને વધારે વાપરવુ જોઇએ નહિં. વર્ણનએ નવા API માટે વાંચનારને ધ્યાન લેવુ જોઇએ.
(FIXME : સ્થિરતા જાણકારી)
/** * 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. Annotations
Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list of the supported tags can be found on the wiki.
/** * foo_get_bar: (annotation) * @foo: (annotation): some foo * * Retrieves @foo's bar. * * Returns: (annotation): @foo's bar */ ... /** * foo_set_bar_using_the_frobnicator: (annotation) (another annotation) * (and another annotation) * @foo: (annotation) (another annotation): some foo * * Sets bar on @foo. */
3.3.3. વિધેય ટિપ્પણી બ્લોક
Please remember to:
- Document whether returned objects, lists, strings, etc, should be freed/unrefed/released.
- Document whether parameters can be NULL, and what happens if they are.
- Mention interesting pre-conditions and post-conditions where appropriate.
Gtk-doc એ '_' સાથે શરૂ થતા બધા સંકેતો (મેક્રો, વિધેયો) ને ખાનગી ધારે છે. તેઓ સ્થિર વિધેયો જેવું વર્ણતૂક કરે છે.
/** * 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. */
- પાછુ આવે છે:
-
ફકરો પાછુ મળેલ પરિણામને વર્ણવી રહ્યા છે.
- @...:
-
In case the function has variadic arguments, you should use this tag (@Varargs: does also work for historic reasons).
3.3.4. ગુણધર્મ ટિપ્પણી બ્લોક
/** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
3.3.5. સંકેત ટિપ્પણા બ્લોક
Please remember to:
- Document when the signal is emitted and whether it is emitted before or after other signals.
- Document what an application might do in the signal handler.
/** * 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.6. Struct ટિપ્પણી બ્લોક
/** * 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 usually a good idea to add a comment block 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.7. Enum ટિપ્પણી બ્લોક
/** * 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.