On Tue, Apr 25, 2023, 3:18 PM Gregory Nutt <spudan...@gmail.com> wrote:
> > > 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 > > The current coding > standardhttps:// > cwiki.apache.org/confluence/display/NUTTX/Coding+Standard#fileorganization > forbids documentation tags in the code, but that could change. > I think you mean this page in the docs :) https://nuttx.apache.org/docs/latest/contributing/coding_style.html?highlight=deoxygen > 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. > I _very_ much agree. I have very rarely found doxygen to be useful and usually just results in unhelpful boilerplate to make the tool happy and generates some html that no one will ever look at again. It is usually much better when someone spends the time to actually document the interfaces and the why behind them (like man pages) we already have a section in the docs for interfaces and it would be great as people extend and adapt them to continue keeping these up to date. Additionally from this discussion I have opened two tickets from this thread. * Generate and publish the PDF alongside the html docs https://github.com/apache/nuttx/issues/9095 * A tracking ticket to unify more of the docs. https://github.com/apache/nuttx/issues/9094 I will start in on both once I return from holiday and have time in front of a real computer again. --Brennan >
