documentation: another proposal to improve our code

[Jeremy Allison]

On Sat, Oct 13, 2012 at 03:58:07PM -0700, Matthieu Patou wrote:
> Hello all,
> 
> It seems that we are in a period of proposal so here is my proposal
> to improve the quality of the project, make review much much much
> more easier, lower the bar for non team member to commit: make
> documentation of each function mandatory.
> 
> That is to say each function that is created and if you modify a
> function that hasn't any documentation you add it too.
> I suppose that I don't need to explain the advantage of this, but
> still I'll do it :-)
> 
> Lately I've been doing a lot of fixes in DRS code and now in ACLs,
> it's non trivial code and sometime the function name didn't give a
> clue of what's going on having documentation helps to figure out
> what's going on and so helps to make more easily modification. For
> new comers it's even more important due to the fact that the code is
> pretty vast and not everybody has 15+ years of history with this
> code (like tridge or jeremy).
> 
> Also I would like to indicate that I praise (silently but still) the
> work Andreas has done on talloc and other libraries that makes life
> much more easier.
> 
> I know that adding documentation is a big task that's why we could
> start with just the new functions as when you are writing code it
> shouldn't be super hard to spend 5 more minutes (or sometimes even
> less) to explain what the function does in comparison to the time
> spent on coding itself it should be negligible.
> I propose that we start this for every new commit on a voluntary
> basis and see how it goes in one month.
> For the most motivated on I proposed to try the full set right now,
> but I can understand that it then tries to take (much?) more time
> than the coding.
> 
> 
> Please comment.

+1 - excellent idea !

Jeremy.