Thanks Alan! This is why I was a bit surprised why the documentation is not direct part of the source code (i.e. documentation of the file/module/function right in that file/module/function). Kivy does that, it helps understanding the code, allows easy online/pdf documentation out of it, and most important keeps documentation coherent and up to date with the code! It could be easier to maintain / keep things coherent.. this can be also done with Sphinx that we already use.. what do you think folks? What are the pros and cons? :-)
The current coding standardhttps://cwiki.apache.org/confluence/display/NUTTX/Coding+Standard#fileorganization forbids documentation tags in the code, but that could change.
My experience with using Deoxygen on large, projects has been disastrous. People don't always maintain the tags to the documentation was wrong and so the auto-generated documentation was not trust-worthy. So you always end up looking at the code anyway. There is nothing in the auto-generated code that is not in the the files so there is no real value added (there would be if you could trust it).
Also, minor errors in the tags cause a lot of CI failures. A couple per week.
I suppose if documentation tags were added to all files and were all of the highest quality, it would be a good thing. That that would be an enormous job and ongoing maintained of the documentation tags would be a problem: Most people won't change them or put in useless, low value tags. Much like PR comments. Or comments and documentation in general.
If we could do it right, then +1 with a significant commitment of time and effort. If we would do only a half-assed job, then -1.
