Where to document APIs?

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?

Thank you,

Alex.
Received on Tue Apr 22 2008 - 13:22:18 MDT