X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=doc%2Fapi%2Flibbabeltrace2%2FREADME.adoc;fp=doc%2Fapi%2Flibbabeltrace2%2FREADME.adoc;h=71675a63795a5f80ab614566ee3a30c64761663c;hp=0000000000000000000000000000000000000000;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9 diff --git a/doc/api/libbabeltrace2/README.adoc b/doc/api/libbabeltrace2/README.adoc new file mode 100644 index 00000000..71675a63 --- /dev/null +++ b/doc/api/libbabeltrace2/README.adoc @@ -0,0 +1,386 @@ +// Render with Asciidoctor + += Babeltrace{nbsp}2 C API documentation guidelines +Philippe Proulx +6 October 2019 + +This document explains how to write documentation for the +Babeltrace{nbsp}2 C API. + + +== General rules + +* Use four spaces to indent. + +* Try to stay behind the 72^th^ column mark if possible. + +* Use `+ +` wherever needed. + +* Refer to a function using the `func()` form and to an enumerator or + type using the `#name` syntax. + +* When you refer to any keyword or definition, use the `\c` command if + it's a single word, otherwise surround the words with `` and + ``: ++ +-- +---- +@returns + Event class on success, or \c NULL on error. +---- +-- + +* Use the `\command` style in text and the `@command` style for other + locations (for example, `@brief`, `@param`, `@sa`, `@file`). + +* Use a `@code{.unparsed}` block for a plain text block (shell input, + for example): ++ +---- +@code{.unparsed} +$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure +@endcode +---- + +* In the text, use `\bt_p{__param__}` to refer to the parameter named + `__param__`. + + +== Function documentation + +Full example: + +---- +/*! +@brief + Does something (third person singular, simple present) with some + parameter \bt_p{param} unless some other parameter + \bt_p{other_param} is some value. + +Full documentation goes here and adds any relevant information that's +not in the brief description. + +@code +/* If needed, put any C code in a code block. */ +@endcode + +Crucifix scenester vegan organic neutra palo santo glossier occupy +truffaut. Meh fixie taiyaki single-origin coffee wayfarers. Thundercats +farm-to-table shoreditch vinyl. + +@remarks + This is where you would put some remarks. Occupy flexitarian neutra, + edison bulb bespoke sriracha post-ironic. Mlkshk plaid pop-up + polaroid chillwave, ennui neutra. + +See this image: + +@image html mein-illustration.png "In elit et." + +@note + @parblock + This is a multiparagraph note. + + Tote bag sartorial distillery, try-hard succulents wayfarers DIY + YOLO four loko jianbing farm-to-table unicorn vice. + + Mumblecore semiotics raw denim palo santo chartreuse helvetica + shabby chic, distillery pabst poke swag copper mug blue bottle. + @endpar + +@attention + Use an attention command if this message is really important. + +@attention + @parblock + An attention block with more than one paragraph: + + @code + some_code(23) + @endcode + + Elit dolore pariatur ex anim officia cupidatat adipisicing mollit + incididunt irure anim nostrud. + @endparblock + +@param[in] param + Description of this parameter. +@param[in] other_param + @parblock + Description of this other parameter. Nulla consequat tempus libero, + sed finibus velit. + + Offal actually vinyl taiyaki kickstarter etsy. + @endparblock +@param[out] out_param + On success, \bt_p{*out_param} contains to something + useful. + +@retval #SOME_STATUS_OK + Success. +@retval #SOME_STATUS_MEMORY_ERROR + Out of memory. +@retval #SOME_STATUS_ERROR + @parblock + Longer description for this specific status. + + Organic locavore sartorial 3 wolf moon brooklyn, VHS pug distillery + schlitz tofu banjo chambray you probably haven't heard of them hot + chicken copper mug. + + Neutra kale chips kombucha, salvia green juice live-edge swag + biodiesel scenester austin yuccie dreamcatcher cronut small batch. + @endparblock + +@bt_pre_not_null{param} +@bt_pre_not_null{other_param} +@bt_pre_hot{param} +@pre + \bt_p{param} is like this or like that. + +@bt_post_ref_cnt_same{other_param} +@post + \bt_p{other_param} is still in some state, and woke jean waistcoat. + +@sa bt_some_other_function() — + Does something else with a parameter. +@sa bt_another_function() — + Cardigan celiac palo santo, tacos chicharrones pitchfork chambray + photo booth subway tile 90's street. +*/ +---- + +Parts: + +. **Opening Doxygen comment**. ++ +Use `/*!`. + +. **Brief description**. ++ +Use third person singular in the simple present tense: you are +documenting what the function does. Assume that the sentence implicitly +starts with "`This function`". ++ +Try to mention, briefly, all the parameters (with `\bt_p`) and what the +function returns. ++ +End the sentence with a period. + + +. **Detailed description**. ++ +Write complete sentences. ++ +Refer to parameters (with `\bt_p`) as much as possible. ++ +In general, keep paragraphs short: often, a single sentence is enough. ++ +Write notes (`@note` command), remarks (`@remark` command), or +attentions (`@attention` command) when appropriate. Most notes and +remarks, however, can be simple paragraphs. Use `@parblock` end +`@endparblock` to have more than one note/remark/warning paragraph. + +. **Parameter descriptions** (if any). ++ +Use the `@param[in]`, `@param[out]`, and `@param[in,out]` commands +depending on the parameter direction. ++ +Document parameters in the declaration order. ++ +Refer to other parameters (with `\bt_p`) when useful for the reader. ++ +End each description with a period. ++ +Use `@parblock` end `@endparblock` to have more than one paragraph for a +given parameter description. ++ +Make sure there's no blank line, except within a `@parblock` block, +within the parameter description block so that Doxygen puts all the +descriptions in the same section. For example, **do not** write this: ++ +---- +@param[in] hexagon + Ugh literally +1 aesthetic, fashion axe try-hard mixtape pork belly + four loko. + +@param[in] selfies + Brooklyn ethical migas, viral edison bulb meggings butcher + flexitarian letterpress humblebrag kombucha pour-over etsy sriracha + blog. +---- + + +. **Return value** (if any). ++ +-- +* If the function returns a status code, use the `@retval` command + multiple times to document each status: ++ +---- +@retval #BT_VALUE_COPY_STATUS_OK + Success. +@retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR + Out of memory. +---- ++ +End each description with a period. ++ +Use `@parblock` end `@endparblock` to have more than one paragraph +for a given return value description. ++ +Make sure there's no blank line, except within a `@parblock` block, +within the return value description block so that Doxygen puts all the +descriptions in the same section. For example, **do not** write this: ++ +---- +@retval #BT_VALUE_COPY_STATUS_OK + Success. + +@retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR + Out of memory. +---- + +* If the function returns a simple value, use the `@returns` command + to document it. ++ +Refer to parameters (with `\bt_p`) when useful for the reader. ++ +End the description with a period. +-- + +. **Preconditions** (if any). ++ +List all the function's preconditions with the `@pre` command or any +alias which starts with `@bt_pre`. ++ +Use the simple present tense. ++ +Do not write the word "`must`" as a precondition is already a +requirement. ++ +End the description with a period. ++ +Make sure there's no blank line within the precondition description +block so that Doxygen puts all the descriptions in the same section. For +example, **do not** write this: ++ +---- +@bt_pre_hot{param} + +@pre + \bt_p{param} is like this or like that. +---- + +. **Postconditions** (if any). ++ +List all the function's _relevant_ postconditions with the `@post` +command or any alias which starts with `@bt_post`. ++ +Anything that the function's documentation body describes and which +forms the nature of the function does not need to be written as an +explicit postcondition. For example, if a function adds some object A +to some object B, do not write the postcondition "B contains A". ++ +Use the simple present tense. ++ +End the description with a period. ++ +Make sure there's no blank line within the postcondition description +block so that Doxygen puts all the descriptions in the same section. For +example, **do not** write this: ++ +---- +@bt_post_ref_cnt_same{other_param} + +@post + \bt_p{other_param} is still in some state, and woke jean waistcoat. +---- + +. **Items to see also** (if any). ++ +Use the `@sa` command, multiple times if needed, to refer to related +functions or types. ++ +This is a way for you to inform the reader about other existing, related +items. Keep in mind that the reader does not always know where to look +for things. ++ +In the referred item's brief description, do _not_ mention its +parameters, if any. ++ +End each brief description with a period. ++ +Make sure there's no blank line within the "`see also`" description +block so that Doxygen puts all the descriptions in the same section. For +example, **do not** write this: ++ +---- +@sa bt_some_other_function() — + Does something else with a parameter. + +@sa bt_another_function() — + Cardigan celiac palo santo, tacos chicharrones pitchfork chambray + photo booth subway tile 90's street. +---- + + +== Writing style + +The ultimate goal of the Babeltrace{nbsp}2 C API documentation is to +make the layman write code using this API as fast and correct as +possible without having to ask for help. For this purpose, the +documentation must 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 `\em` command (one word) or by surrounding the text to +emphasize with `` and ``. Likewise, you can use strong emphasis +when needed with the `\b` command (one word) or with `` and +``. In general, prefer light emphasis to strong emphasis, and +use it economically. + +Links to other parts of the documentation are very important. Consider +that the reader never knows that other functions exist other than the +one she's reading. Use as many internal links as possible. Use the +following forms of links: + +`__func__()`:: + Automatic link to the function or macro named `__func__`. + +`#__name__`:: + Automatic link to the type or enumerator named `__name__`. + +`\ref __ref__`:: + Link to `__ref__` (page name, group name, function or macro name, + type name, variable name, etc.) using its default text. + +`\ref __ref__ "__some text__"`:: + Link to `__ref__` (page name, group name, function or macro name, + type name, variable name, etc.) using the text `__some text__`. + +See Doxygen's http://www.doxygen.nl/manual/autolink.html[Automatic link +generation] for other ways to create automatic links. + +Follow, as much as possible, the +https://docs.microsoft.com/en-ca/style-guide/welcome/[Microsoft Style +Guide] when you document the API. This includes: + +* Use an active voice. +* Use a gender-neutral language. +* Use the present tense (you almost never need the future tense). +* Address your reader directly (use "`you`"). +* Use contractions ("`it's`", "`you're`", "`don't`", and the rest). +* 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`", and + that's very clear for the reader.