Boost itself does not require any specific documentation structure. The - C++ Standard, however, has very explicit requirements for the description - of library components (Section 17.3). So for Boost libraries likely to be - proposed for inclusion in the standard, it is highly desirable to structure - documentation in a way that meets the requirements of the the standard. - Doing so eliminates the need to rewrite the documentation for - standardization.
- -Library developers should remember that for a library to be accepted as - part of the C++ Standard Library, the proposal must include full wording. - The committee will not do that work for you.
- -Beyond that, the documentation structure required for the standard is an - effective way to communicate the technical specifications for a library. - Although terse, it is already familiar to many Boost users, and is far more - precise than most ad hoc documentation structures.
- -The following description is for the structure of documentation required - by the standard. Boost libraries should also provided additional - documentation, such as introductory, tutorial, example, and rationale - material.
+Boost does not require any specific documentation structure. + However, there are some important considerations that + influence content and structure. For example, many Boost + libraries wind up being proposed for inclusion in the C++ + Standard, so writing them initially with text suitable for + inclusion in the Standard may be helpful. Also, Boost library + documentation is often accessed via the World Wide Web, + including via search engines, so context is often important + for every page. Finally, Boost libraries should provide + additional documentation, such as introductory, tutorial, + example, and rationale content. With those things in mind, we + suggest the following guidelines for Boost library + documentation.
The documentation structure required for the C++ Standard is + an effective way to describe the technical specifications for + a library. Although terse, that format is familiar to many + Boost users and is far more precise than most ad hoc formats. + The following description is based upon §17.3 of the + Standard. (Note that while final Standard proposals must + include full standardese wording, which the committee will + not do for you, that level of detail is not expected of Boost + library documentation.)
+Each document contains the following elements, as applicable(1):
+ "footnote" href="#footnote1" id="footnote1-location">(1):In some cases the semantic requirements are presented as C++ code. Such code is intended as a specification of equivalance of a construct to another construct, not necessarily as the way the construct must be - implemented.(2)
+ implemented.(2)Descriptions of class member functions follow the order (as - appropriate)(3):
+ appropriate)(3):Descriptions of function semantics contain the following elements (as - appropriate)(4):
+ appropriate)(4):Boost library documentation is often accessed via the World + Web. Using search engines, a page deep in the reference + content could be viewed without any further context. + Therefore, it is helpful to add extra context, such as the + following, to each page:
+ +It is also useful to consider the effectiveness of a + description in search engines. Terse or cryptic descriptions + are less likely to help the curious find a relevant function + or type.