The main reason for me not writing
beautiful doxygen documentation is that it is actually more work
to get it to look readable than a wiki.
The only package I'm aware of like this is joy:
Unlike most other packages, the node and parameter docs are
on the doxygen page rather than the wiki page— I find this
actually more confusing than helpful. Is there another better
example of this idea?
This is indeed confusing. I figured the correct/best practice way
was to describe the interface directly at the wiki level. Its the
most visible and easiest to navigate. Completely auto generating
interface Information is quite hard if you don’t want to reverse
engineer every code automatically. So the developer has to describe
it somewhere. Rather than putting more into the doxygen I would be
in favour of having a best practice for what should be presented at
the wiki page for a bare minimum. (I think the wiki tutorials state
somewhere that you should at least provide interface descriptions).
Alternatively, if we like the joy package as an example,
how can we elevate the visibility of the doxygen page content
on the ROS wiki page? For example, by a macro which could suck
it in and display it there.
But wouldn’t it be much nicer to use the nicely formated macros for
this? I think it`s a huge benefit that most of the wiki pages look
the same in regard to this interface definition. By pulling this
information out of the page you would loose this nice uniformity.
You could of course parse the doxygen, but if there is already a
nice macro to fill out, why not use that?
The doxygen documentation is quite visible for anyone searching for
it. The user that just wants to work with the node does not need
that information most of the time as it contains much more than he
would want to know. The right place for interface documentation
should be at the wiki page level. Anything going beyond that is
probably fine within the API description.
Regarding auto generated content: I think the current wiki structure
is quite good as it is. A lot of the information is auto generated
from the doc jobs giving you the instant achievement if everything
is green at the top of your wiki page, links to the repo, stati of
jenkins builds and so on. The Doxygen is auto generated and quite
visible at the top of your documentation. Also I think the wiki adds
valuable information that could not be adequately be captured within
a file contained just in the source code. Of course you could do a
very nice doxygen documentation but that is much harder than writing
a nice wiki page including some pictures or even a youtube link of
the package in action.
Also In my opinion the current way of having macros for different
versions of a release is the best way to handle that. As Dirk
pointed out, the API is auto generated for every release so the most
up to date information can be found there. Even if the interfaces
change during releases they will most likely not change completely.
Also the rest of the documentation (concepts, failure handling,
requirements etc.) will probably stay mostly the same. So I am in
favour of small change macros instead of big copies with small
changes.
Best Regards
Georg
_______________________________________________
ros-users mailing list
ros-users@lists.ros.org
http://lists.ros.org/mailman/listinfo/ros-users
--
.........................................................
M.Sc. Georg Heppner
Wissenschaftlicher Mitarbeiter Interaktive Diagnose- und Servicesysteme (IDS)
FZI Forschungszentrum Informatik
Haid-und-Neu-Str. 10–14
76131 Karlsruhe, Germany
Tel.: +49 721 9654-248
Fax: +49 721 9654-249
heppner@fzi.de
www.fzi.de
.........................................................
FZI Forschungszentrum Informatik am Karlsruher Institut für Technologie
Stiftung des bürgerlichen Rechts
Stiftung Az: 14-0563.1 Regierungspräsidium Karlsruhe
Vorstand: Prof. Dr. Andreas Oberweis, Prof. Dr. Ralf Reussner,
Jan Wiesenberger, Prof. Dr.-Ing. J. Marius Zöllner
Vorsitzender des Kuratoriums: Ministerialdirigent Günther Leßnerkraus
.........................................................