Re: [Xenomai-core] broken docs

[Jan Kiszka <jan.kiszka@domain.hid>]

[-- 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 --]