Re: Where to document APIs?

On Thu, 2008-09-11 at 16:32 +0800, Adrian Chadd wrote:
> 2008/9/11 Alex Rousskov <rousskov_at_measurement-factory.com>:
>
> >> To clarify:
> >>
> >> Longer API documents, .dox file in docs/, or maybe src/ next to the .cc
> >>
> >> Basic rules the code need to fulfill, or until the API documentation
> >> grows large, in the .h or .cc file.
> >
> > You all have seen the current API notes for Comm and AsyncCalls. Do you
> > think they should go into a .dox or .h file?
> >
> > I think they are big enough (and growing) to justify a .dox file. I will
> > probably add those files to trunk (next to the corresponding .h files)
> > unless there are better ideas.
>
> Whats wrong with inline documentation again?

You mean as a large blob of comments at the end of some .h file? The
cons are:

- Mixing [C++] code with [Doxygen] markup has a few drawbacks: Many
class declarations are already becoming unreadable with a regular
editor, IMO. Some formatting and code analysis tools may be confused by
large portions of Doxygen markup.

- Updating such documentation would often require complete Squid
rebuild. This will discourage some folks from polishing the docs while
working on the code.

- There are often several related .h files, making it less obvious where
to find the documentation.

- Easier to isolate code changes from documentation changes (e.g.,
during review).

- Increasing .h file size slows down the compiler (yes, a minor point)

On the other hand, placing API docs in .h files makes them "closer" to
the code which might keep docs and code more in sync.

For large API descriptions, I think .dox or similar wins.

Alex.
Received on Thu Sep 11 2008 - 15:54:55 MDT