Re: Where to document APIs?

Alex Rousskov wrote:
> Hello,
>
> Recent Squid3 discussions mentioned a set of rules or guarantees for
> AsyncCalls and Comm APIs. Where do you think these things should be
> documented?
>
> * Source code, header files: More chances to keep the description up to
> date and version-specific but in the way of day-to-day development
> activities and more difficult to modify, especially without fancy source
> code editors and once the code is released. Doxygen can do basic
> rendering.
>
> * Source code, .cc files: Same as header files but possibly less in the
> way of day-to-day development. Doxygen can do basic rendering.
>
> * Wiki: Easy to modify, no need to skip when developing, but more
> chances of getting out of date. Somewhat better rendering and discussion
> abilities.
>
> * Other?

* Source code .dox file: Essentially a .cc but with no compilable code.
Just the specially formatted comments. This keeps it out of the .h and
.cc files and developers way. But comes with a penalty that some updates
_may_ make them incorrect (same applies to wiki). Doxygen can do the
rendering, .h and .cc files can reference it into any adaption API.

Amos

-- 
Please use Squid 2.6.STABLE19 or 3.0.STABLE4