Re: [Xenomai-core] broken docs
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 " * \" to " * @" > 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.
Re: [Xenomai-core] broken docs
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 " * \" to " * @" > 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. ___ Xenomai-core mailing list Xenomai-core@gna.org https://mail.gna.org/listinfo/xenomai-core
Re: [Xenomai-core] broken docs
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 long 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 " * \" to " * @" 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
Re: [Xenomai-core] broken docs
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 long 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 " * \" to " * @" 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
Re: [Xenomai-core] broken docs
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 long 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 signature.asc Description: OpenPGP digital signature
Re: [Xenomai-core] broken docs
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 long 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
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 long evenings of continuous patching the docs, recompiling, and checking the result. Any volunteers - I'm lacking the time? :-/ Jan signature.asc Description: OpenPGP digital signature
RE: [Xenomai-core] broken docs
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 : [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] 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
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 long 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 signature.asc Description: OpenPGP digital signature ___ Xenomai-core mailing list Xenomai-core@gna.org https://mail.gna.org/listinfo/xenomai-core
Re: [Xenomai-core] broken docs
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 long 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. ___ Xenomai-core mailing list Xenomai-core@gna.org https://mail.gna.org/listinfo/xenomai-core
Re: [Xenomai-core] broken docs
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 long evenings of continuous patching the docs, recompiling, and checking the result. Any volunteers - I'm lacking the time? :-/ Jan signature.asc Description: OpenPGP digital signature ___ Xenomai-core mailing list Xenomai-core@gna.org https://mail.gna.org/listinfo/xenomai-core
RE: [Xenomai-core] broken docs
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 : [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] 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 ___ Xenomai-core mailing list Xenomai-core@gna.org https://mail.gna.org/listinfo/xenomai-core
