RTEMS SuperCore Doxygen

[Robert S. Grimes]

Joel Sherrill wrote:
> Hi,
>
> Over the past couple of years, I have slowly worked
> on an unpaid pet project of mine -- converting the
> comments in the core .h files in RTEMS to Doxygen.
>   
This is great!  As a relatively new RTEMS application developer, I am 
often grep'ing through header files for the real types of arguments when 
the "RTEMS Applications C User's Guide" (CUG) is out-of-date.  There are 
a lot of these issues.  A fine example of how documentation lags the 
code when the two are done separately!
> I have completed enough of the SuperCore to the
> point where I think it is good enough to debut. YEAH!!
>
> It is automatically rebuilt every 6 hours and is online at
>   
Auto-rebuild - that's great!
> http://www.rtems.org/doxygen/score/html/index.html
>
> I encourage the community to help this improve by 
> editing .h files or financially contributing to
> further improvements.  I really would like to see
> the Classic API, POSIX API, and SAPI .h files
> documented this way.  That leaves a lot to do.
>   
I would suggest you set up auto-rebuilding for these, as it would 
encourage people to contribute, IMHO.  I know that when I use Doxygen, I 
document my code much better when I see the results of my efforts - I 
suppose that's the "instant gratification" plague in action, I'm\ 
afraid!  Still, the more we can encourage others to contribute...

There are two issues that come to mind.

1. Potential Code Breakage
First, one potential problem with documenting in the source code is 
inadvertent changes to the actual code when only documentation was the 
intent.  For example, as a mere user, I would be happy to help by 
documenting things that I have just looked up during my work, and 
spending a bit of time to contribute the appropriate comments; however, 
I might be hesitant to do so because I could inadvertently break 
something, and I'm not sure I'm up to validating this hasn't occurred.

As it is, I can't actually check anything in anyway, which is probably a 
Good Thing :-P !  Do you envision an  alternate means for contributing 
Doxygen comments?

2. Descriptive Text
Ultimately, it would be great to include the narrative descriptions of 
various facilities, such as the text in the aforementioned CUG.  I would 
suggest those materials be put in files other than the real header 
files, to keep the latter to reasonable sizes.  From my experience, 
striving to keep the details out of the narrative helps to keep the 
latter current.  The hyperlinking Doxygen generates allows the 
(relatively static) higher-level docs to link to (relatively dynamic) 
details, which is tremendously useful for users and maintainers alike!

Seems I have two major points:

  1.  This is a great idea, at least as great as the Wiki, and certainly 
has huge potential to really increasing the usability (and subsequent 
viability) of RTEMS!

  2. Think really hard about how to include the wider community in 
this!  Should changes be proposed somewhere (perhaps the mailing list, 
or the Wiki) by anyone, and when appropriately reviewed, submitted by 
Joel or someone?

Great job, as usual!
-Bob
> --joel
>
> _______________________________________________
> rtems-users mailing list
> rtems-users at rtems.com
> http://rtems.rtems.org/mailman/listinfo/rtems-users
>
>