Re: Where to document APIs?

> On Thu, 2008-04-17 at 17:53 +1200, Amos Jeffries wrote:
>> 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.
>
> Should the .dox file go into src/, next the the corresponding .cc and .h
> files? Or should it go into doc/Programming-Guide/?
>
> At this point, I am interested in collecting formal API guarantees, not
> writing a true Guide, but it feels like .dox files should go into
> doc/Programming-Guide.

The ones I have written so far have all been in doc/Programming-Guide. Due
only to the fact that they started there.

My view is that the major formal API are going to end up as internal
library sub-directories right?
In which case it feels cleaner to me to have them inside the appropriate
lib directory. Otherwise we will eventually end up with
doc/Programming-Guide/ as cluttered with API docs as src/ is with code
files today.

It also leaves third-parties with clear boundaries on their new
sub-components. Both at the code level and for documentation.

Amos
Received on Tue Apr 22 2008 - 13:13:58 MDT