Re: [Xenomai-core] broken docs

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

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