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

[Bob Carlson]

If you look carefully at my message, I did not suggest that an interface be
documented in each .c file that implements that interface. I suggested the
opposite. My example was the channel interface and I suggested specifically
that it should have been documented once in channel.h. I would have been
happy with documentation in a wiki too.

I use visual slick edit for Linux and for Windows. It gives me immediate
access to all definitions of any symbol and a complete cross reference to
any symbol, so I can look at every example of usage of anything in a few
minutes. In many cases this is still not enough. It certainly wasn't in the
channel case. There is simply too much going on. I still cannot be certain
I understand all the requirements. I am forced to resort to trial and error
in many cases and I have to hope that my testing will be sufficient.

I can't comment on the example you gave. Sorry about that, but I don't have
time to pursue code I don't need to change.

I have another example though. The tone generator facility will be valuable
and important to me. I need to alter it because the floating point
(double!) calculations are waaaayyy too expensive in an embedded system
with no HW FP. I've just begun digging, but it seems that it is not well
documented either. In this case, it appears to be self contained enough
that I will be able to fully understand it and if I do alter it, I will
probably include some improved commentary.

Cheers, Bob

-----Original Message-----
From: asterisk-dev-bounces at lists.digium.com
[mailto:asterisk-dev-bounces at lists.digium.com] On Behalf Of Kevin P.
Fleming
Sent: Wednesday, May 18, 2005 7:43 AM
To: Asterisk Developers Mailing List
Subject: Re: [Asterisk-Dev] Need help to get into the code

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).
_______________________________________________
Asterisk-Dev mailing list
Asterisk-Dev at lists.digium.com
http://lists.digium.com/mailman/listinfo/asterisk-dev
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev