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

[Jerris, Michael MI]

How about a func_skel.c in the functions directory with heavy comments
on the interfaces as there is already for apps, along with a basic note
of purpose in each of the func_ files, plus perhapse a reference to the
func_skel.c for additional information?

> 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 :)
>