[Bug 1647] Modular SuperCore Scheduler

[bugzilla-daemon at rtems.org]

https://www.rtems.org/bugzilla/show_bug.cgi?id=1647

Sebastian Huber <sebastian.huber at embedded-brains.de> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |sebastian.huber at embedded-br
                   |                            |ains.de

--- Comment #12 from Sebastian Huber <sebastian.huber at embedded-brains.de> 2010-08-12 02:20:12 CDT ---
(In reply to comment #11)
> (In reply to comment #7)
[...]
> > + Your Doxygen comments do not document the parameters.
> > 
> Do I need to add param descriptions if I use the @a paramname in the
> description of what the function does?
[...]

We have no general consent here.  Joel favors the parameter tables.  I think
they are a waste of time.  They lead to inconsistencies between simple and
complex functions.  They lead to bloated comments with a lot of copy and paste.
 It is better to give the parameters useful names than adding a comment to
explain them.  The interactions and dependencies of different parameters should
be described together and not in separation.

I think it is very unfortunate that we don't have a Doxygen comment guideline
yet.

There are good examples that use the @a paraname style.  It is the Qt
documentation and the man pages for standard functions (POSIX, Linux, BSD). 
Simply look at the man page of memcpy() for example.  You will find no
parameter table.

What is useful is the @return and in particular the @retval usage.  For an
example look here:

http://www.rtems.org/onlinedocs/doxygen/cpukit/html/group__rtems__interrupt__extension.html

This is the style I would use for the RTEMS documentation.

-- 
Configure bugmail: https://www.rtems.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching all bug changes.