PERFORCE change 120191 for review

[Alexander Leidinger]

Quoting Hans Petter Selasky <hselasky at FreeBSD.org> (from Mon, 21 May  
2007 20:03:59 GMT):

> http://perforce.freebsd.org/chv.cgi?CH=120191
>
> Change 120191 by hselasky at hselasky_mini_itx on 2007/05/21 20:03:52
>
> 	Add tons of documentation to my Linux USB emulation layer.

You use a non-standard comment style.

If you want to improve this, you can have a look at  
dev/sound/pcm/mixer.c. For example the function mixer_get_recroute()  
or mix_setrecdevs() has doxygen-style documentation (but  
mixer_get_recroute() is missing an explanation for the route  
parameter). It's not hard, just some minor reformatting. It also  
serves as an example of good function documentation.

If you use this kind of markup, you will not only get the  
call/include-graph on a doxygen run, but also a nice API  
documentation. If you use the "@internal" keyword  
(http://www.stack.nl/~dimitri/doxygen/commands.html#cmdinternal), you  
can mark a function as internal to your stack, the rest will be the  
official API to use the USB stack. A doxygen command reference is at  
http://www.stack.nl/~dimitri/doxygen/commands.html and the complete  
documentation is available at  
http://www.stack.nl/~dimitri/doxygen/manual.html for reading. A  
downloadable version is available too (see the menu on the right side).

Bye,
Alexander.

-- 
The first rule of intelligent tinkering is to save all the parts.
		-- Paul Erlich

http://www.Leidinger.net    Alexander @ Leidinger.net: PGP ID = B0063FE7
http://www.FreeBSD.org       netchild @ FreeBSD.org  : PGP ID = 72077137