[Xenomai-core] broken docs

[Xenomai-core] broken docs

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 558 bytes --]

Hi,

I noticed that the doxygen API output is partly broken. Under the
nucleus and native skin modules most functions became variables. I
haven't looked at the source yet, but I guess it should be resolvable,
especially as the RTDM docs are fine. This mail is to file the issue,
maybe I will have a look later - /maybe/.

Moreover, I was lacking a reference to RT_MUTEX_INFO. Does this
structure just needs to be added to the correct doxygen group? I guess
there are other undocumented structures out there as well (RT_TASK_INFO,
...?).

Jan


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]

RE: [Xenomai-core] broken docs

[ROSSIER Daniel]

Dear Xenomai workers,

Would it be possible to have an updated API documentation for Xenomai 2.0.x ? (I mean with formal parameters in function prototypes)

I tried to regenerate it with make generate-doc, but it seems that a SVN working dir is required.

It would be great.

Thanks a lot

Daniel

> -----Message d'origine-----
> De : xenomai-core-bounces@domain.hid [mailto:xenomai-core-bounces@domain.hid] De
> la part de Jan Kiszka
> Envoyé : mercredi, 18. janvier 2006 20:03
> À : xenomai-core
> Objet : [Xenomai-core] broken docs
> 
> Hi,
> 
> I noticed that the doxygen API output is partly broken. Under the
> nucleus and native skin modules most functions became variables. I
> haven't looked at the source yet, but I guess it should be resolvable,
> especially as the RTDM docs are fine. This mail is to file the issue,
> maybe I will have a look later - /maybe/.
> 
> Moreover, I was lacking a reference to RT_MUTEX_INFO. Does this
> structure just needs to be added to the correct doxygen group? I guess
> there are other undocumented structures out there as well (RT_TASK_INFO,
> ...?).
> 
> Jan

Re: [Xenomai-core] broken docs

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 867 bytes --]

ROSSIER Daniel wrote:
> Dear Xenomai workers,
> 
> Would it be possible to have an updated API documentation for Xenomai
> 2.0.x ? (I mean with formal parameters in function prototypes)
> 
> I tried to regenerate it with make generate-doc, but it seems that a
> SVN working dir is required.
> 
> It would be great.

I just had a "quick" look at the status of the documentation in
SVN-trunk (2.1). Unfortunately, doxygen is a terrible tool (to express
it politely) when it comes to tracking down bugs in your formatting.
Something is broken in all modules except RTDM, and although I spent *a
lot* of time in getting RTDM correctly formatted, I cannot tell what's
wrong with the rest. This will require some looooong evenings of
continuous patching the docs, recompiling, and checking the result. Any
volunteers - I'm lacking the time? :-/

Jan


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]

Re: [Xenomai-core] broken docs

[Gilles Chanteperdrix]

Jan Kiszka wrote:
 > ROSSIER Daniel wrote:
 > > Dear Xenomai workers,
 > > 
 > > Would it be possible to have an updated API documentation for Xenomai
 > > 2.0.x ? (I mean with formal parameters in function prototypes)
 > > 
 > > I tried to regenerate it with make generate-doc, but it seems that a
 > > SVN working dir is required.

make generate-doc is needed for maintenance only. If you want to
generate doxygen documentation, simply add --enable-dox-doc to Xenomai
configure command line.

 > > 
 > > It would be great.
 > 
 > I just had a "quick" look at the status of the documentation in
 > SVN-trunk (2.1). Unfortunately, doxygen is a terrible tool (to express
 > it politely) when it comes to tracking down bugs in your formatting.
 > Something is broken in all modules except RTDM, and although I spent *a
 > lot* of time in getting RTDM correctly formatted, I cannot tell what's
 > wrong with the rest. This will require some looooong evenings of
 > continuous patching the docs, recompiling, and checking the result. Any
 > volunteers - I'm lacking the time? :-/

Looking at the difference between RTDM documentation blocks and the
other modules is that the other modules use the "fn" tag. Removing the
"fn" tag from other modules documentation blocks seems to solve the
issue.

-- 


					    Gilles Chanteperdrix.

Re: [Xenomai-core] broken docs

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 1808 bytes --]

Gilles Chanteperdrix wrote:
> Jan Kiszka wrote:
>  > ROSSIER Daniel wrote:
>  > > Dear Xenomai workers,
>  > > 
>  > > Would it be possible to have an updated API documentation for Xenomai
>  > > 2.0.x ? (I mean with formal parameters in function prototypes)
>  > > 
>  > > I tried to regenerate it with make generate-doc, but it seems that a
>  > > SVN working dir is required.
> 
> make generate-doc is needed for maintenance only. If you want to
> generate doxygen documentation, simply add --enable-dox-doc to Xenomai
> configure command line.
> 
>  > > 
>  > > It would be great.
>  > 
>  > I just had a "quick" look at the status of the documentation in
>  > SVN-trunk (2.1). Unfortunately, doxygen is a terrible tool (to express
>  > it politely) when it comes to tracking down bugs in your formatting.
>  > Something is broken in all modules except RTDM, and although I spent *a
>  > lot* of time in getting RTDM correctly formatted, I cannot tell what's
>  > wrong with the rest. This will require some looooong evenings of
>  > continuous patching the docs, recompiling, and checking the result. Any
>  > volunteers - I'm lacking the time? :-/
> 
> Looking at the difference between RTDM documentation blocks and the
> other modules is that the other modules use the "fn" tag. Removing the
> "fn" tag from other modules documentation blocks seems to solve the
> issue.
> 

Indeed, works. Amazingly blind I was.

Anyway, it still needs some work to remove that stuff (I wonder what the
"correct" usage of @fn is...) and to wrap functions without bodies via
"#ifdef DOXYGEN_CPP" like RTDM does. At this chance, I would also
suggest to replace all \tag by @tag for the sake of a unified style (and
who knows what side effects mixing up both may have).

Jan


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]

Re: [Xenomai-core] broken docs

[Jan Kiszka]

[-- Attachment #1: Type: text/plain, Size: 3057 bytes --]

Jan Kiszka wrote:
> Gilles Chanteperdrix wrote:
>> Jan Kiszka wrote:
>>  > ROSSIER Daniel wrote:
>>  > > Dear Xenomai workers,
>>  > > 
>>  > > Would it be possible to have an updated API documentation for Xenomai
>>  > > 2.0.x ? (I mean with formal parameters in function prototypes)
>>  > > 
>>  > > I tried to regenerate it with make generate-doc, but it seems that a
>>  > > SVN working dir is required.
>>
>> make generate-doc is needed for maintenance only. If you want to
>> generate doxygen documentation, simply add --enable-dox-doc to Xenomai
>> configure command line.
>>
>>  > > 
>>  > > It would be great.
>>  > 
>>  > I just had a "quick" look at the status of the documentation in
>>  > SVN-trunk (2.1). Unfortunately, doxygen is a terrible tool (to express
>>  > it politely) when it comes to tracking down bugs in your formatting.
>>  > Something is broken in all modules except RTDM, and although I spent *a
>>  > lot* of time in getting RTDM correctly formatted, I cannot tell what's
>>  > wrong with the rest. This will require some looooong evenings of
>>  > continuous patching the docs, recompiling, and checking the result. Any
>>  > volunteers - I'm lacking the time? :-/
>>
>> Looking at the difference between RTDM documentation blocks and the
>> other modules is that the other modules use the "fn" tag. Removing the
>> "fn" tag from other modules documentation blocks seems to solve the
>> issue.
>>
> 
> Indeed, works. Amazingly blind I was.
> 
> Anyway, it still needs some work to remove that stuff (I wonder what the
> "correct" usage of @fn is...) and to wrap functions without bodies via
> "#ifdef DOXYGEN_CPP" like RTDM does. At this chance, I would also
> suggest to replace all \tag by @tag for the sake of a unified style (and
> who knows what side effects mixing up both may have).
> 

Here is a shell script aiming at an automated fix for parts of the
mentioned issues. Anyone with better shell hacking skills may improve it
(I'm always willing to learn!).

for file in `find -name "*.[c|h]"`; do
    mv $file $file.tmp
    cat $file.tmp | (
        echo $file
        while read -r; do
            # delete " * @fn ..." lines
            new_line="`echo "$REPLY" | sed 's/\ \*\ @fn[^$]*$//' | \
                tr -d "\n"`"
            if echo "$REPLY" | grep -q '\ \*\ @fn[^$]*$'; then
                # delete empty comment lines succeeding " * @fn ..."
                read -r
                if [ "$REPLY" != " *" ]; then
                    echo "$REPLY" >> $file
                fi
            else
                # convert " * \<tag>" to " * @<tag>"
                echo "$new_line" | sed 's/\ \*\ \\\([a-z]\)/ * @\1/' \
                    >> $file
            fi
        done
    )
    rm $file.tmp
done


I only tested it on ksrs/skins/native, but it seems to work - for those
functions with a body :-/. We still need to manually wrap body-less
function docs as it is done in the rtdm skin. But I think this is a start.

Jan


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 252 bytes --]

Re: [Xenomai-core] broken docs

[Gilles Chanteperdrix]

Jan Kiszka wrote:
 > Jan Kiszka wrote:
 > > Gilles Chanteperdrix wrote:
 > >> Looking at the difference between RTDM documentation blocks and the
 > >> other modules is that the other modules use the "fn" tag. Removing the
 > >> "fn" tag from other modules documentation blocks seems to solve the
 > >> issue.
 > >>
 > > 
 > > Indeed, works. Amazingly blind I was.
 > > 
 > > Anyway, it still needs some work to remove that stuff (I wonder what the
 > > "correct" usage of @fn is...) and to wrap functions without bodies via
 > > "#ifdef DOXYGEN_CPP" like RTDM does. At this chance, I would also
 > > suggest to replace all \tag by @tag for the sake of a unified style (and
 > > who knows what side effects mixing up both may have).
 > > 
 > 
 > Here is a shell script aiming at an automated fix for parts of the
 > mentioned issues. Anyone with better shell hacking skills may improve it
 > (I'm always willing to learn!).
 > 
 > for file in `find -name "*.[c|h]"`; do
 >     mv $file $file.tmp
 >     cat $file.tmp | (
 >         echo $file
 >         while read -r; do
 >             # delete " * @fn ..." lines
 >             new_line="`echo "$REPLY" | sed 's/\ \*\ @fn[^$]*$//' | \
 >                 tr -d "\n"`"
 >             if echo "$REPLY" | grep -q '\ \*\ @fn[^$]*$'; then
 >                 # delete empty comment lines succeeding " * @fn ..."
 >                 read -r
 >                 if [ "$REPLY" != " *" ]; then
 >                     echo "$REPLY" >> $file
 >                 fi
 >             else
 >                 # convert " * \<tag>" to " * @<tag>"
 >                 echo "$new_line" | sed 's/\ \*\ \\\([a-z]\)/ * @\1/' \
 >                     >> $file
 >             fi
 >         done
 >     )
 >     rm $file.tmp
 > done
 > 
 > 
 > I only tested it on ksrs/skins/native, but it seems to work - for those
 > functions with a body :-/. We still need to manually wrap body-less
 > function docs as it is done in the rtdm skin. But I think this is a start.

The point is that the @fn tags improve readability of documentation
blocks, so, it would be nice if we could keep them. Simple tests with
the same Doxyfile as Xenomai show that the @fn tag works as expected, so
the problem may be due to something else. Now that I think about it,
the way we dealt with EXPORT_SYMBOL in Doxyfile is probably the culprit,
and the fix looks quite simple on elementary tests.

-- 


					    Gilles Chanteperdrix.