RTEMS SuperCore Doxygen

[Joel Sherrill]

Robert S. Grimes wrote:
> 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!
>   
The documentation set for the CVS head is also
updated automatically every 6 hours now and
is at:

http://www.rtems.org/onlinedocs/doc-current/share/rtems/html/
>> 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!
>   
If it doesn't destroy the output like it did last night
when it ran the first time automatically. :-D
>> 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...
>
>   
The other directories I mentioned have NOT been converted
to Doxygen.  A few files that have been modified recently have
been converted and some may have a routine here or there
commented in Doxygen format --  but that's about it.

Believe it or not, most of the information in the score header files
was already present.  It just needed to be in Doxygen format.
> 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.
>   
If you submit a patch to Doxygen comments, part of
validating them will be for me (or whomever merges it)
to run  Doxygen.  If you break something, we will have to
fix it or punt it back with comments.

Under Fedora, Doxygen is easy to install since it is a
regaulr RPM.  So Linux users shouldn't have trouble
testing any changes.
> 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?
>   
No.  Since they are in the code, I still think it has to be a
CVS diff against the head.
> 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!
>
>   
Thanks.  It was a long time getting to the point it could
be done this way.

I have considered having "Joel's RTEMS Blog" -- would
if be of interest?
>   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?
>
>   
I had thought about posting a Wiki page with a list of files
that are to be converted to Doxygen and let people sign up
for some.  File count for .h and .inl.

cpukit/rtems - 52
cpukit/sapi - 9
cpukit/posix - 34

Since most have the raw information and just need to
be formatted per Doxygen, it is more tedious than hard.

I can post a "work sign up sheet" if people are willing to
pitch in.  This does NOT require great detailed knowledge.
> Great job, as usual!
>   
Thanks.

--joel

> -Bob
>   
>> --joel
>>
>> _______________________________________________
>> rtems-users mailing list
>> rtems-users at rtems.com
>> http://rtems.rtems.org/mailman/listinfo/rtems-users
>>
>>
>>