On Fri, 2002-01-25 at 03:11, Jens Owen wrote:
> Jos� Fonseca wrote:
>
> > Unless anyone has a better suggestion I think this is the way to go. What
> > do the "elder" developers think?
>
> The one down side I see is the complexity (and clutter) created by the
> TAGS. I like simple
> paragraphs myself. Perhaps we could encourage a very basic simple
> template for most things, so the comments are still easy to read and
> maintain when editing the code itself.
>
> -- /\
> Jens Owen / \/\ _
> [EMAIL PROTECTED] / \ \ \ Steamboat Springs, Colorado
The tags are quite transparent and they are only used in the functions
descriptions. As in:
/**
* Used to open the main /dev/drm
* control device. If running as root, this device is
* automatically created in /dev with the appropriate
* mode.
*
* \note This function replaces drmOpenDRM in the old DRI
* documentation.
*
* \returns a file descriptor for the main /dev/drm
* control device, or a negative value on error.
*/
static int drmOpenDevice(long dev, int minor)
{
...
There is no point in putting tags inside a function body because (at
least) Doxygen doesn't document a function inner working.
In fact a perhaps better alternative would be document only the headers
files instead of the implementation so that the code remains lean. (The
downside would be bigger include fields and more C preprocessing time
but the includes files are just used inside XFree86 tree and the
difference in the build time would be almost negligible.)
Regards,
Jose Fonseca
_______________________________________________
Dri-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/dri-devel
