--- /dev/null
+= 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 bt_ctf_stream_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 space 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 / commitdiff
