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.
