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. Thank you, Alex.
