documentation: another proposal to improve our code

[Matthieu Patou]

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.

Matthieu.

-- 
Matthieu Patou
Samba Team
http://samba.org