On Tue, Apr 25, 2023, 6:10 PM Tomek CEDRO <to...@cedro.info> wrote: > 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? >
Eh I don't think we should pull the docs apart. Its a pain to manage especially with sphinx if we start sprinkling the docs all over the place. it's also hard in my opinion to write clear cohesive docs thare do not get highly repetitive if each section lives in isolation. This unified style is also what we seen in projects like Zephr and Linux https://github.com/torvalds/linux/tree/master/Documentation https://github.com/zephyrproject-rtos/zephyr/tree/main/doc All this said, there is no reason to not also write clear comments in the code, especially code that may be incomplete, complex, hiding dragons or otherwise confusing. --Brennan >
