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
