-= Babeltrace C API documentation guidelines
-
-Please follow those guidelines when you add to or modify the existing
-documentation of the Babeltrace C API.
-
-
-== Syntax
-
-Syntax example to document a function (tabs are converted to spaces
-in this example, but you really _must_ use tabs to indent):
-
-----
-/**
-@brief Sets the name of the CTF IR stream class \p stream_class
- to \p name.
-
-\p name must be unique amongst the names of all the stream classes
-of the trace class to which you eventually add \p stream_class.
-
-@remarks
-This is where you would put some remarks. Lorem ipsum dolor sit amet,
-consectetur adipiscing elit. Vestibulum sagittis tristique velit vitae
-tincidunt.
-
-@warning
-Use a warning command if this message is really important.
-
-@param[in] stream_class Stream class of which to set the name.
-@param[in] name Name of the stream class (copied on success). If
- the description is too long, continue on the
- next line like this.
-@returns 0 on success, or a negative value on error.
-
-@prenotnull{stream_class}
-@prenotnull{name}
-@prehot{stream_class}
-@pre Some custom precondition.
-@postrefcountsame{stream_class}
-@post Some custom postcondition.
-
-@sa btstream_class_get_name(): Returns the name of a given stream class.
-*/
-----
-
-**Rules**:
-
-* Try to stay behind the 72th column mark if possible, and behind the
- 80th column otherwise.
-
-* Start the block with
- https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdbrief[`@brief`]
- followed by a tab followed by the brief description. If the brief
- description needs more than one line, start the following lines with a
- tab character.
-+
-Try to always refer to all the function or macro parameters in the brief
-description. The sentence _must_ begin with a verb, third-person
-singular. The brief description _must_ contain a single sentence
-which ends with a period.
-+
-Follow the brief description by zero or more paragraphs giving more
-details about the object you are documenting.
-+
-You can also use the
-https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdremark[`@remarks`]
-and
-https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdwarning[`@warning`]
-commands as needed to add special paragraphs.
-
-* When you refer to parameters, use the
- https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdp[`\p`]
- command:
-+
---
-----
-@brief Transfers the ownership of a Babeltrace object from variable
- \p _var_src to variable \p _var_dst.
-----
---
-
-* When you refer to any keyword or definition, use the
- https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdc[`\c`]
- command if it's a single word, otherwise surround the words with
- `<code>` and `</code>`:
-+
---
-----
-@returns Event class on success, or \c NULL on error.
-----
---
-
-* Add a new line before the parameter descriptions.
-
-* The syntax for a parameter line is one of:
-+
---
-----
-@param[in] in_param Input parameter description.
-@param[out] out_param Output parameter description.
-@param[in,out] inout_param Input/output parameter description.
-----
---
-+
-That is:
-+
---
-. https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdparam[`@param`]
-. `[in]` (input parameter), `[out]` (output parameter), or `[in,out]`
- (input/output parameter).
-+
-Output and input/output parameters are
-always pointers where, for a parameter named `param`, a result is
-stored _into_ `*param`.
-
-. A space.
-. The name of the parameter.
-. At least one tab.
-. The description which ends with a period.
---
-+
-Make sure all the beginnings of the parameter descriptions and of the
-return value description are vertically aligned by using as many tabs as
-required.
-+
-If more than one line is needed, align the beginning of the second line
-with the beginning of the first one (see the return value description in
-the example above).
-
-* The syntax for the return value line is:
-+
---
-. https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdreturns[`@returns`]
- (_not_ `@return`).
-. At least one tab.
-. The description which ends with a period.
---
-+
-The return value description often takes the form:
-+
---
-----
-X on success, or Y on error.
-----
---
-
-* When needed, add an empty line after the return value line and add
- preconditions and postconditions with the
- https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdpre[`@pre`]
- and
- https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdpost[`@post`]
- commands on the following lines.
-+
-Preconditions are a very clear way to indicate what the documented
-function or macro expects from the user in relation to its parameters.
-+
-Postconditions are a very clear way to indicate what the user should
-expect from the documented function or macro once it returns.
-+
-Use complete sentences, starting with a capital letter and ending with
-a period, when writing conditions. Use the present tense. If there's a
-conditional part, put it in bold at the beginning of the sentence.
-+
-If the condition is too long for a single line, continue on the
-following line, after a tab.
-+
-Examples:
-+
---
-----
-@pre The size of \p array_obj is equal to the size of \p map_obj.
-@post <strong>On success</strong>, the reference count of \p array_obj
- is incremented.
-@post The reference count of \p map_obj is not modified.
-----
---
-+
-IMPORTANT: You should use aliases when possible to avoid duplication.
-See the list of available aliases in the `Doxyfile.in` file.
-
-* When relevant, add a new line after the return value line (or after
- the precondition or postcondition lines, if any) and add
- as many _see also_ links as needed on the following lines.
-+
-The syntax of those lines is:
-+
---
-. https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdsa[`@sa`]
-. A single space.
-. The name of the function, macro, variable, group, file, or page name
- to see also.
-. `:` (colon).
-. A single space.
-. The capitalized brief description which ends with a period. The
- sentence _must_ begin with a verb, third-person singular.
---
-+
-This is a way for you to inform the reader about other existing, related
-functions, macros, or any other documentation. Keep in mind that the
-reader does not always know where to look for things.
-+
-If the description is too long for a single line, continue on the
-following line, after a tab:
-+
---
-----
-@sa some_function() Lorem ipsum dolor sit amet, consectetur adipiscing
- cras iaculis lectus quis dolor congue tempor.
-----
---
-
-* Always prefer the `@` commands to the `\` commands when you use them
- outside of the text itself.
-
-
-== Style
-
-The ultimate goal of the Babeltrace C API documentation is to make the
-layman write code using this API as fast as possible without having to
-ask for help. For this purpose, the documentation should always be as
-clear as possible, just like the function and type names try to be.
-
-Do not hesitate to repeat technical terms, even in the same sentence, if
-needed. For example, if you document a _value object_, then always use
-the term _value object_ in the documentation, not _value_, nor _object_,
-since they are ambiguous.
-
-You can use light emphasis to show the importance of a part of the text
-with the
-https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdem[`\em`]
-command (one word) or by surrounding the text to emphasize with `<em>`
-and `</em>`. Likewise, you can use strong emphasis when needed with the
-https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdb[`\b`]
-command (one word) or with `<strong>`/`</strong>`. In general, prefer
-light emphasis to strong emphasis.
-
-Links to other parts of the documentation are very important. Consider
-that the reader never knows that other functions exist other than the
-current one. Use as many internal links as possible. Use the following
-forms of links:
-
-* `func()`: automatic link to the function (or macro) `func()`.
-* `file.h`: automatic link to the file named `file.h`.
-* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdref[`\ref
- group`]: link to the
- https://www.stack.nl/\~dimitri/doxygen/manual/grouping.html[group]
- named `group` (prefer this over a link to a file).
-* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdref[`\ref
- variable`]: link to the variable `variable`.
-* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdlink[`\link
- reference some text\endlink`]: link to `reference` (file name, group
- name, function or macro name, etc.) using the text `some text`.
-+
-Example:
-+
---
-----
-You can create a \link events CTF IR event\endlink using [...]
-By calling \link func() said function\endlink, [...]
-----
---
-+
---
-[NOTE]
-.Doxygen limitation.
-====
-Do not put a space between the end of the text and the `\endlink`
-command, because this space becomes part of the hyperlink's text.
-
-Do _not_ do:
-
-----
-You can create a \link events CTF IR event \endlink using [...]
-By calling \link func() said function \endlink, [...]
-----
-====
---
-
-See Doxygen's
-https://www.stack.nl/\~dimitri/doxygen/manual/autolink.html[Automatic
-link generation] for other ways to create automatic links.
-
-Try to follow as much as possible the
-https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual of Style]
-(4th edition) when you document the API. This includes:
-
-* Use an active voice.
-* Use a gender-neutral language.
-* Use the present tense (you should never need the future tense).
-* Address your reader directly (use _you_).
-* Avoid anthropomorphism.
-* Ensure parallelism in lists, procedures, and sentences.
-* Terminate list items with a period.
-* Do not use Latin abbreviations.
-* Use _and_ or _or_ instead of a slash.
-* Avoid using negatives.
-* Avoid using _should_: most of the time, you mean _must_.
-
-
-== Babeltrace terminology
-
-Here are the official names of the Babeltrace objects that you must use
-as is in the API documentation:
-
-* Value objects:
-** The null value object (_the_, not _a_, since it's a singleton
- variable)
-** Boolean value object
-** Integer value object
-** Floating point number value object
-** String value object
-** Array value object
-** Map value object
-* CTF IR field path object
-* CTF IR field types
-** CTF IR integer field type
-** CTF IR floating point number field type
-** CTF IR enumeration field type
-** CTF IR string field type
-** CTF IR array field type
-** CTF IR sequence field type
-** CTF IR structure field type
-** CTF IR variant field type
-* CTF IR fields:
-** CTF IR integer field
-** CTF IR floating point number field
-** CTF IR enumeration field
-** CTF IR string field
-** CTF IR array field
-** CTF IR sequence field
-** CTF IR structure field
-** CTF IR variant field
-* CTF IR clock class
-* CTF IR event class
-* CTF IR stream class
-* CTF IR trace class
-* CTF IR event
-* CTF IR packet
-* CTF IR stream
-* CTF IR writer
-* Component
-* Source component
-* Sink component
-* Component class
-* Source component class
-* Sink component class
-* Plugin
-* Notification
-* Iterator
-
-Note that once you mention _CTF IR_ in an object name, you can omit
-it in the few following paragraphs.
projects / babeltrace.git / blobdiff