documentation: another proposal to improve our code

[Volker Lendecke]

On Sun, Oct 14, 2012 at 09:01:36PM -0700, Jeremy Allison wrote:
> 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 !

For the tevent_req continuation functions I would like to
have an exception. _send and _recv -- sure, but doing the
same for all the _done function which I try to name very
verbosely, I don't know if describing "subreq" parameter
and the void return value over and over again gives much
additional value.

Volker

-- 
SerNet GmbH, Bahnhofsallee 1b, 37081 Göttingen
phone: +49-551-370000-0, fax: +49-551-370000-9
AG Göttingen, HRB 2816, GF: Dr. Johannes Loxen
http://www.sernet.de, mailto:kontakt at sernet.de