Re: Where to document APIs?

On Sun, Apr 20, 2008 at 8:23 PM, Alex Rousskov
<rousskov@measurement-factory.com> wrote:
>
> 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.

I'd keep them close to their source-files, as it'd be more clear a
reminder to developers to update them.

-- 
 /kinkie