documentation: another proposal to improve our code

[Andreas Schneider]

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:

http://www.vim.org/scripts/script.php?script_id=987

" doxygen vim config
let g:DoxygenToolkit_authorName="Andreas Schneider"
let g:DoxygenToolkit_licenseTag="GPL"
let g:DoxygenToolkit_undocTag="DOXIGEN_SKIP_BLOCK"
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

-- 
Andreas Schneider                   GPG-ID: F33E3FC6
Samba Team                             asn at samba.org
www.samba.org