From: Philippe Proulx Date: Wed, 16 Nov 2016 08:01:44 +0000 (-0500) Subject: doc/api: add README.adoc X-Git-Tag: v2.0.0-pre1~699 X-Git-Url: http://git.efficios.com/?a=commitdiff_plain;ds=sidebyside;h=3758cf401cebb5f099f4f09795b4fbcda1cf4e42;p=babeltrace.git doc/api: add README.adoc Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- diff --git a/doc/api/Makefile.am b/doc/api/Makefile.am index e2b05c48..75c75dd8 100644 --- a/doc/api/Makefile.am +++ b/doc/api/Makefile.am @@ -7,6 +7,7 @@ install-data-local: doxygen-doc MOSTLYCLEANFILES = $(DX_CLEANFILES) EXTRA_DIST = Doxyfile.in \ + README.adoc \ dox/group-api-ref.dox \ dox/group-ctf-ir.dox \ dox/main-page.dox \ diff --git a/doc/api/README.adoc b/doc/api/README.adoc new file mode 100644 index 00000000..52179820 --- /dev/null +++ b/doc/api/README.adoc @@ -0,0 +1,352 @@ += 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 + `` and ``: ++ +-- +---- +@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 On success, 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 `` +and ``. 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 ``/``. 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.