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. 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'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 >
