120500b5cb
the Doxygen documentation. Documenters can just put *.dox files into the documentation/text/ directory which describe how to do things with MetalSVM. making_coffee.dox is still missing - anyone?
112 lines
3.1 KiB
Text
112 lines
3.1 KiB
Text
/**
|
|
* @file documenting.dox
|
|
* @page documenting Documenting MetalSVM with Doxygen
|
|
*
|
|
* The doxygen project has a nice manual at http://www.stack.nl/~dimitri/doxygen/manual.html \n
|
|
* All content on this page is extracted from there.
|
|
*
|
|
* Please check if the \c doxygen command throws errors on your documented code.
|
|
*
|
|
* @section inline Documenting code inline
|
|
*
|
|
* To document your code correctly, you will have to follow some (simple) rules:
|
|
*
|
|
* Place a comment block like this at the beginning of your source code files you intend to document:
|
|
*
|
|
* @verbatim
|
|
/**
|
|
* @author John Doe
|
|
* @file path/to/your/file.h
|
|
* @brief A brief explanation about what this code does or is supposed to do.
|
|
*/@endverbatim
|
|
*
|
|
* Functions/procedures are commented in the header file just above the
|
|
* function/procedure definition:
|
|
*
|
|
* @verbatim
|
|
/** @brief Blocking wait for semaphore [short explanation]
|
|
*
|
|
* [space for more detailed explanations]
|
|
*
|
|
* [describing parameters]
|
|
* @param s Address of the according sem_t structure
|
|
* @param ms Timeout in milliseconds
|
|
*
|
|
* [describing possible return values in a list]
|
|
* @return
|
|
* - 0 on success
|
|
* - -EINVAL on invalid argument
|
|
* - -ETIME on timer expired
|
|
*/
|
|
inline static int sem_wait(sem_t* s, uint32_t ms); @endverbatim
|
|
*
|
|
* Documenting structures and their members looks like the following:
|
|
* @verbatim
|
|
/** @brief The task_t structure */
|
|
typedef struct task {
|
|
/// Task id = position in the task table
|
|
tid_t id;
|
|
/// Task status (INVALID, READY, RUNNING, ...)
|
|
uint32_t status;
|
|
... @endverbatim
|
|
*
|
|
* @section formatting Formatting text
|
|
*
|
|
* Although you could use HTML brackets to format your text,
|
|
* Doxygen provides special commands. Please use those, since it is possible
|
|
* that someone may want to generate CHM, Latex or other formatted output
|
|
* from this documentation.
|
|
*
|
|
* To \e emphasize, \b highlight or \c typewrite text, use the following commands:
|
|
* \verbatim To \e emphasize, \b highlight or \c typewrite text... \endverbatim
|
|
*
|
|
* \verbatim
|
|
Preserving the format
|
|
of text like
|
|
this can be done with \verbatim end \ endverbatim \endverbatim
|
|
*
|
|
* Code will be color-highlighted with \\code and \\endcode:
|
|
* \code
|
|
int i;
|
|
for (i=0; i < 123; i++)
|
|
printf("%d\n", i);
|
|
\endcode
|
|
*
|
|
* It is also easily possible to make listings:
|
|
* - item a
|
|
* - item b
|
|
* - item c
|
|
*
|
|
* And also enumerated listings:
|
|
* -# item a
|
|
* -# item b
|
|
* -# item c
|
|
*
|
|
* \verbatim
|
|
It is also easily possible to make listings:
|
|
- item a
|
|
- item b
|
|
- item c
|
|
|
|
And also enumerated listings:
|
|
-# item a
|
|
-# item b
|
|
-# item c \endverbatim
|
|
*
|
|
* @section docs Writing documents like this one
|
|
*
|
|
* To write a stand-alone manual like this one, just create
|
|
* a file \c your_manual.dox in \c $MSVM/documentation/text/.
|
|
*
|
|
* This file's content should look like this:
|
|
*
|
|
* \verbatim
|
|
/**
|
|
* @file your_manual.dox
|
|
* @page your_manual This is your manual's title. It will be displayed in the "Manuals" section.
|
|
*
|
|
* @section your_section This starts a section with a title
|
|
*
|
|
* content, content, content!
|
|
*/ \endverbatim
|
|
*/
|