On Tue, Apr 25, 2023 at 5:47 PM Brennan Ashton wrote: > On Tue, Apr 25, 2023, 3:18 PM Gregory Nutt wrote: > > 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.
Okay, Doxygen is the past.. currently Sphinx is the way to go, no doubts, just an (not really convenient) example to keep doc in sync with src and that can be quite PITA :-) After some consideration a "safer" approach may be more desirable for now: 1. Migrate all documentation to a separate Documentation/ as it is currently done, so we do not lose any content from MediaWiki/README/CWIKI, we can add additional content that we need, the documentation form is shaped to a satisfactory state, automation is verified, nice references, tables of contents, sections, etc. People will have solid documentation all the time and we cause no mess and we can see how the work on doc goes in reality :-) 2. When we have a well shaped "separate" documentation then it may be the time to consider merging it with the source code, but not before, if desired at all? What do you think? The biggest pro for keeping doc within src is to stay in sync, maybe to also have self documented source code. But there are also dangers here, like messing up the whole unfinished doc and the source code!! It would be wise to list all pros and cons and then after some time make some decisions but not necessarily right now.. :-) Pros: 1. It would be more coherent to keep doc inside src files and this will result in better doc-in-sync-with-src. 2. Source code will have documentation "inside". 3. Sphinx has a better syntax than Doxygen so less ci / format / tag errors may occur. 4. Working examples are available as reference point (https://github.com/kivy/kivy/tree/master/doc, https://github.com/kivy/kivy/blob/master/kivy/config.py). Cons: 2. It can (and probably will) mess up current doc _and_ src!! 2. Separation of documentation from the source code will enable easy switch to other documentation system rather than rewrite of all source code. 3. This is even more work than migrating docs from wiki. 4. This will make source files bigger (any impact on (pre)process/build time or something?). 5. The "separate" documentation is already out there just needs reformatting (wiki -> rst). > 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. I am in, already subscribed! Full work power should arise around July.. I will send some testing PR in the meantime. Thanks!! :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
