Hardware manual

67
7.3. Documentation.
Documentation for bldctest.c and for bldc.c was generated automatically with help of script
written in Perl, called: kernel-doc
4
. Exactly the same script is used to generate the
documentation for kernel sources and because of that there are couples of rules which are
important to keep in mind during creation of documentation.
Firstly, if we want to describe some function, we can do it in the following way:
/**
* name_of_the_function – short description of the function which we describe
* @some_arg: here is description of this argument
*
* Here can be some longer explanation of the function.
*
* Example:
* name_of_the_function(1);
*/
The keyword Example: states that we want to put some example how to call function.
Whenever we want to describe structure, union, enum or typedef before its name we need to
write the type of definition: struct/union/enum/typedef. Here is small example:
/**
* struct some_structure - short description
* @a: first member
* @b: second member
*
* Here can be some longer explanation of the
structure.
*/
struct some_ structure {
char a;
long b;
};
Additionally it is possible to mark some other elements like: environmental variables,
constants... The full list was taken from examples in the script and is shown below:
4
This script can be downloaded from: http://kernel.org/pub/linux/kernel/people/marcelo/linux-2.4/scripts/kernel-
doc