Re: [boost] Re: Review: Boost Coding Guidelines

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-07-20 09:40:44

At 04:14 PM 7/18/2001, John Max Skaller wrote:

 >jeff_at_[hidden] wrote:
 >
 >> As previously mentioned by someone
 >> else, the key reason for formatting requirements is consistency amongst 
a
 >> development team, and so this is certainly less of an issue for boost
 >except
 >> during library review.
 >
 >Human readability isn't the only issue. Compilers ignore comments
 >and formatting style. Compilers aren't the only useful tools.
 >Documentation extraction tools are also useful, and they
 >require different standards to operate correctly, such as
 >assuming which comments are associated with which entities.
 >
 >If boost users want to be able to extract interface documentation
 >from source, then boost needs rules -- not guidelines --
 >about things like comment placement.

I don't think automatic extraction is likely anytime soon, even if a few 
developers are using the technique.

There was once some Boost discussion of improved documentation tools, 
particularly DocBook/XML. http://www.oasis-open.org/docbook/

If we want to put effort into documentation tools, I think DocBook/XML 
should be the starting point rather than worrying about automatic 
extraction.

--Beman