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 >
