[Asterisk-Dev] Need help to get into the code

[Luigi Rizzo]

On Mon, May 16, 2005 at 08:49:37AM -0700, Kevin P. Fleming wrote:
...
> > actually at the very least it would deserve a generic comment
> > near the top (perhaps there is a template for this ?)
> > 
> >  * this is the standard function template, described in <...>
> >  * The specific function implemented by this file is described
> >  * in the "struct ast_custom_function" that you can find below.
> 
> But don't you already know that based on the name/location of the file 
> and it's stated purpose (at the top of the file)? Sure, if you take the 
> file completely out-of-context then it would be harder to figure out 
> what it is doing, but that is not really a useful thing to do :-)

well, when the context is huge as in the case of asterisk,
newcomer to the project like me have a hard time finding pointers to
documentation -- in fact for me that is still problematic.
Personally, i like to keep documentation as close as possible to
the code implementing it, to be able to do quick consistency checks.

Also, I find maintaining consistency between documentiation and
implementation of interfaces a very useful exercise -- it forces
one to stop and think to restate things in a different language,
which often leads to discover of bugs "hey, i did not really
implemented this!"

Now please don't say i am taking CS201 and want to evangelize the world :)

> Anyone who thinks the code is under-commented is more than welcome to 
> provide what they feel is appropriate commenting in the form of patches...

my vote would be for the 3 lines above replacing <...> with the
appropriate file name which i don't know :)

cheers
luigi