documentation: another proposal to improve our code
asn at samba.org
Mon Oct 15 03:32:13 MDT 2012
On Saturday 13 October 2012 15:58:07 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.
Thanks, I hope all of you have installed:
" doxygen vim config
let g:DoxygenToolkit_authorName="Andreas Schneider"
let g:DoxygenToolkit_briefTag_funcName = "no"
let g:DoxygenToolkit_commentType = "C"
let g:DoxygenToolkit_briefTag_pre = " @brief "
let g:DoxygenToolkit_briefTag_post = ""
let g:DoxygenToolkit_paramTag_pre = " @param[in] "
let g:DoxygenToolkit_paramTag_post = " "
let g:DoxygenToolkit_returnTag = " @return "
let g:DoxygenToolkit_fileTag = " @file "
let g:DoxygenToolkit_authorTag = " @author "
let g:DoxygenToolkit_dateTag = " @date "
let g:DoxygenToolkit_blockTag = " @name "
let g:DoxygenToolkit_classTag = " @class "
let g:DoxygenToolkit_startCommentTag = "/**"
let g:DoxygenToolkit_startCommentBlock = "/*"
let g:DoxygenToolkit_interCommentTag = "*"
let g:DoxygenToolkit_endCommentTag = "*/"
let g:DoxygenToolkit_endCommentBlock = " */"
vim has a filetype c.doxygen to hightlight the documentation too.
Andreas Schneider GPG-ID: F33E3FC6
Samba Team asn at samba.org
More information about the samba-technical