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

[Kevin P. Fleming]

Bob Carlson wrote:

> I believe Kevin said that he always comments code that is not
> self-explanatory and provides documentation by and for developers. He
> considers the existing comments to be sufficient for a "non-casual" reader.
> I believe it was also Kevin who was using an example of dial plan code. He
> said something to the effect that "If you just know the context of dial
> plan modules, you don't need any commentary." This is exactly the problem.
> The comments that are missing are those that provide the context, the
> overview. No one, least of all me, wants comments of the variety "i++; /*
> increment counter */". I want to know the intent behind the interface, the
> rules, the options and the illegal combinations.

That's fine, but why does that need to be in the code that's being 
_called_? (Your original example was func_callerid.c, which makes very 
few API calls of its own).

The 'context' of func_callerid.c is a given, there is no need for 
comments to say "this is a dialplan function, look in pbx.c for the 
functions that call the functions provided here". In fact, if you start 
with ast_custom_function_register, that will lead you to pbx.c, and 
'struct ast_custom_function'. If you look at all functions in pbx.c that 
deal with 'struct ast_custom_function', you will see the 
registration/deregistration functions, the lookup function, and the 
functions that make the read/write calls. Please tell me where 
additional comments would have been helpful there, other than saving you 
a 5-second grep search (or if you use ctags/etags, a zero-second tag 
lookup).

Also, 'make progdocs' (with doxygen and graphiz installed) is very 
helpful as well, because it will tell you what functions call what other 
functions (although not via function pointers, obviously).