> 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
