I disagree with the assertion that more code documentation is better. The doxygen documentation, when taken to its full extent, duplicates the code it references. This encourages bad practices such as relying on documentation instead of ensuring the code itself is readable and understandable. It also adds overhead such that changes to methods/variables need to be reflected in comments. This can lead to a discrepancy between the documentation and the code.
I urge us to think very carefully about what level of doxygen support we need before going down this route. Doxygen runs with the comments we already have will be a huge improvement over the current state without having to add another layer on top. On Thu, Aug 7, 2014 at 1:04 PM, Benjamin Hindman <[email protected]> wrote: > Adding more code documentation will only help! Thanks for getting this > going Niklas! We'll need some documentation on how to write that > documentation too. ;-) > > For those folks interested in "higher-level" documentation, like what I had > created for stout here > < > https://github.com/apache/mesos/blob/master/3rdparty/libprocess/3rdparty/stout/README.md > >, > I'd love to work with folks to do this for libprocess too (and/or increase > the coverage of stout). Please reach out! > > > On Thu, Aug 7, 2014 at 12:52 PM, Niklas Nielsen <[email protected]> > wrote: > > > Inlined. > > > > > > On 7 August 2014 10:46, Dominic Hamon <[email protected]> > wrote: > > > > > On Aug 6, 2014 4:33 PM, "Niklas Nielsen" <[email protected]> wrote: > > > > > > > Hi guys, > > > > > > > > I think it is in communities interest to lower the barrier to entry > for > > > new > > > > contributors to the project. Not only in terms of process (as BenH > has > > > been > > > > putting a lot of effort into - bravo!) but also in terms of making it > > > > easier to understand the inner workings of Mesos. > > > > So far, it is more or less "Go look at the implementation" approach > or > > > > having Mesos developers explain the details on the mailing lists to > get > > > > deeper than the design discussions we have on JIRA or the few > > > > subsystem/architecture docs we have on wiki and in docs/. > > > > Not that this is a bad thing, but I think we could do a better job in > > > > codifying it a bit - one step could be to make source browsing and > > > > documentation generation (such as doxygen - I am not religious about > > > that) > > > > in place. > > > > > > > > If this is already on-going and hosted, let me know and I'll try to > do > > a > > > > better job staying informed. If not, how about starting a > conversation > > > on: > > > > > > > > 1) A style of doxygen annotations we can agree on (We have a Doxyfile > > > > already in the repo) > > > > 2) Start encouraging incoming patches to comment on public classes, > > > methods > > > > and variables > > > > 3) Start automating generation of those and host it, like we host the > > > > Javadoc at http://mesos.apache.org/api/latest/ > > > > > > > > Thoughts? > > > > > > > > > > > > > I'd like to start with a browsable code repository and existing > comments > > > to see how good that is before requiring doxygen comments. > > > > > > > > Will get that setup tomorrow. Thanks for the pointers Dave! > > > > > > > Having comments on class API formatted to doxygen style is a barrier > to > > > entry and goes against the principle that public APIs on classes should > > be > > > self-documenting. Comments should be reserved for tricky behaviour > > rather > > > than for everything in the code-base. > > > > > > I do not agree with it raising the barrier to entry - on the other hand, > > how can "not documenting" be a motivation for lowering the bar? > > New contributors have to read tons of code to grasp the context of tiny > > portions of the code base (that has been our experience). > > Core concepts and components has to be rediscovered every time and it > > hasn't been condensed into documentation by people that wrote it or got > to > > understand it. > > > > I did not have a strict method/variable documentation process in mind but > > we are already leaving blobs of comments around classes that are > > complicated / hard to understand. > > I am not rooting for commenting self explanatory code (i.e. int count //< > > This is a count.), but I think there are vast areas of under-documented > > classes and subsystems. > > Doxygen just would be one way of getting that in place with > > class/namespace/file cross-referencing. > > > > > > > > > > I'm all for having doxygen running and the results published as I think > > the > > > benefits to having the architecture documented are huge. Especially if > > the > > > report can contain dependency graphs. I need a lot of convincing before > > > I'll support wholesale doxygen commenting for interfaces. > > > > > > > > > > > > > > > > > Cheers, > > > > Niklas > > > > > > > > > > > That was my few cents; I think it is an important discussion to have and > I > > would love to hear other people's opinion too. > > > > Niklas > > > -- Dominic Hamon | @mrdo | Twitter *There are no bad ideas; only good ideas that go horribly wrong.*
