I don't think we need to take the doxygen documentation "to its full extent", or even enforce documenting every public class/method. I personally get annoyed at unhelpful @params and @returns. But I agree that having the existing class/method comments published in a source-browsable format would be very helpful. And any newly added documentation should expand the utility of publishing it, not add more noise.
On Thu, Aug 7, 2014 at 1:22 PM, Dominic Hamon <[email protected]> wrote: > 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.* >
