X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=doc%2Fapi%2FREADME.adoc;fp=doc%2Fapi%2FREADME.adoc;h=0000000000000000000000000000000000000000;hp=3e6ce69f76048944eed34ea9f2c03cd98ce97c87;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9 diff --git a/doc/api/README.adoc b/doc/api/README.adoc deleted file mode 100644 index 3e6ce69f..00000000 --- a/doc/api/README.adoc +++ /dev/null @@ -1,351 +0,0 @@ -= 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 - `` 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.