on Sat Dec 01 2007, Joel de Guzman <joel-AT-boost-consulting.com> wrote:
My opinion on this is to keep the boost/detail *solely* for core libraries use. For non-core libraries, it is always better to use boost/<library>/detail and boost::<library>::detail as many libraries are already doing. If they need to be used by other libraries, then my thinking is that they ought not to be in detail, but rather, hosted by a parent library, just like that suggested in the last item in the list of current "practices". Then, the natural place for its documentation is the host library (e.g. The proto docs are currently in xpressive, the pre-review of fusion was once in spirit).
That doesn't always work. For example, I have a number of tiny utilities in Boost.Python that I needed to re-use in Boost.Iterator. Having Boost.Iterator depend on Boost Python would be totally inappropriate, so after I got things working I moved these components into boost/detail. That's the way boost/detail ought to be used. These components are tested and commented, but they are pretty obscure, and making them into public Boost components would entail writing rationales, tutorials, and formal interface documentation. I didn't have time for that, and almost nobody would have benefited from it: adding more oddball components into the list at http://boost.org/libs will only make it harder to find the useful stuff. Sometimes a really general and useful component will end up in boost/detail (or <libraryname>/detail) because the author just doesn't have time to do what it takes to make it a public part of the Boost interface. That's legitimate, too; this is a volunteer effort, after all. If someone wants it in the public interface badly enough, he or she can take responsibility for getting it there. That's what ha -- Dave Abrahams Boost Consulting http://www.boost-consulting.com