Re: A new strategy for internals documentation

Yao Qi
2013-08-10T01:13:06Z

On 08/09/2013 07:04 AM, Doug Evans wrote:
> I'm one that thinks that there is not enough, and that expanding the
> comments is not enough. For one there's a higher level / descriptive
> view that's missing with that approach. Plus the S/N ratio when faced
> with reading all the source code is much lower than when able to
> browse something generated from the comments in the code.

Code comments can be about high-level view too. Existing comments in
the beginning of event-loop.h and remote-notif.c are about high-level
view.

Document is generated from the comments, and we need some special
annotations or markups to identify these comments are descriptive views
for a certain module or components. Doxygen or other documentation
generators are able to do that.

--
Yao (é½å°§)