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
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Xenomai-core mailing list Xenomai-core@gna.org https://mail.gna.org/listinfo/xenomai-core
