metalsvm/documentation/text/documenting.dox

/**
 * @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
 */