David Abrahams wrote: > "Edward Diener" <[EMAIL PROTECTED]> writes: > >>> Not hard, no, but it certainly takes more time than it might appear. >>> FWIW, I've started such a section for dynamic_bitset. The doc file, >>> for now, is in the boost sandbox, subfolder /libs/dynamic_bitset. >> >> I am glad to see you doing that. I still don't understand all the >> pain that many others seem to feel in documenting what they are >> doing. >> >>> >>>> If I were a >>>> library implementor, whether Boost or otherwise, I would want to >>>> explain my ideas to the outside world as a way of promoting good >>>> technology. >>> >>> Ahehm... :-) >> >> An extra 'h' maybe <g>. Or is it just extra phlegm that got stuck in >> your throat when you typed it <g><g>. >> >> Actually I am quite serious with my preceding paragraph. I have >> never quite understand why so many good, and often brilliant >> programmers, take it so hard when others suggest that they document >> what they do in easily understandable sentences. There must be >> something wrong in the educational systems of the countries from >> which most programmers come when they can not, or do not, want to >> write clearly. Yet many of the Boost implementors do write well when >> they attempt to do so. > > Maybe you should try writing a library as a volunteer sometime and see > what happens to your standards for others' work.
I have written a library but not a Boost library ( http://www.tropicsoft.com/Components/RegularExpression ). I am always surprised when programmers, such as yourself in this instance, react so vehemently to those who suggest that documentation can be better in any respect. I don't think of writing documentation as easy, and I am sure my own is as flawed as much other documentation is, but the merest suggestion to improve documentation standards for programmers always meets with a similar response which you have given here. > It is difficult and > time-consuming enough to write coherent user-level documentation as > required by Boost that IMO it's unreasonable to demand implmentation > documentation at the same level. All I asked for is that when changes were made between releases to a library a small amount of documentation be given which elucidates what those changes were in a general way. It would help both users of a Boost library and 3rd party developers of a Boost library, as it would enable both parties to track general changes and adapt their understanding of the library from within their own code to those changes. _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
