On Tue, Apr 25, 2023 at 8:46 AM Brennan Ashton <bash...@brennanashton.com> wrote: > > > > 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
Before I do more work to wire this up, please let me know if this pdf I have attached here seems like a reasonable start for people https://github.com/apache/nuttx/issues/9095#issuecomment-1547008998 It is basically the same content on the website, so missing information is out of scope of this change, but I don't want to fix some compatibility issues here unless people actually think this is of value. --Brennan
