On Thu, 2007-08-16 at 10:21 +1200, Amos Jeffries wrote: > What I'm hoping for is to have a paragraph for each class about where its > intended to be used etc.
That would be terrific! I was trying to provide that for the classes I was adding. > Theres lots of little bits still need doing for the Mem component. > You can see what it looks like at: > http://squid.treenet.co.nz/Doc/Code/MemPool_8h.dyn#2eab9a6fa490ed842eeee6a1800e0ec4 > > I think maybe it's the text-description not making it clear its a > code-example. That description needs fixing. Yeah, I can hardly grok the current doxygen rendering. Said that, I care more about how .h looks, and the change makes it look "worse", IMO. Perhaps it will all be much better after the next round of "fixing", but I fear that I will spend more time trying to find and understand things before the doxygen invasion. But again, this is not a huge deal. > > None of these changes are a big deal, of course. I am just worried about > > the general trend of hiding code behind overly verbose documentation... > > > > Does doxygen support some kind of \include mechanism where verbose > > documentation can be moved away from the code while still being linked > > to specific code pieces? Detailed documentation is great, but if it > > makes the actual code difficult to see, it is doing more harm than good, > > IMO. > > Yes, but that defeats the entire purpose of this project. Having the > documentation at the point of code where it will get noticed for change by > any average-joe editors altering that code. I don't expect it to be huge. Yes, I understand the motivation, but every solution taken to the extreme becomes a problem. For example, it would be clearly inappropriate to explain what a C++ class means or how a C++ macro works next to every (or any!) Squid class or macro declaration. Similarly, inserting a chapter on Squid performance optimization next to StoreEntry declaration is wrong. Overly verbose comments are almost as bad as the missing ones. We should not forget that correct, maintainable _code_ is the primary goal. Good code should not require many verbose comments. And too many verbose comments obscure good code. Again, these are general trend-setting observations. The specific example that prompted me to write this is not the most extreme case of verbosity. > I've had a hard time converting the SGML because it references only 2.5 > examples and function names, describing how they behave in 2.5, and had to > check each function operation and change some of it in migration. Sure. And there are lots of obsolete comments in Squid _sources_ as well! Alex.
