DOXYGEN/BOOSTBOOK/QUICKBOOK LIMITATIONS AND GUIDELINES
WARNING: The contents of this page are not the result of a consensus of the Boost community.
Please feel free to improve this page directly or post on the Boost mailing lists boost-AT-lists.boost.org and boost-users-AT-lists.boost.org.
Doxygen Limitations
C++03 features not supported
Inheriting from a template parameter
template <typename UT, typename Bool=bool>
struct inherited_from_underlying
{
template <typename Final, typename Base>
struct type : Base {
// ^^^^
};
};
gives
template <typename UT, typename Bool=bool>
struct inherited_from_underlying {
// member classes/structs/unions
template <typename Final, typename Base>
struct type {
// ^^^^
};
};
::type misplaced when inheriting from a metafunction
template<
typename Final,
typename UT,
typename MetaMixinSeq=boost::mpl::vector0<>,
typename Base=base_opaque_type
>
class new_class : public linear_hierarchy<MetaMixinSeq, Final, Base>::type {
// ^^^^
gives
template<typename Final, typename UT,
typename MetaMixinSeq = boost::mpl::vector0<>,
typename Base = base_opaque_type>
class new_class : public linear_hierarchy::type< MetaMixinSeq, Final, Base > {
// ^^^^
BoostBook Limitations
doxygen tags not supported
Currently there are some doxygen tags that are not taken in account by BoostBook.
@tparam
@see
C++0x features not supported
There are some C++0x features that are not yet supported. These should be added in future versions as soon as the doxygen version you use take care of them.
explicit conversion operator
C++0x explicit operators are not documented as explicit
explicit operator underlying_type const&() const ^^^^^^^
gives
operator underlying_type const&() const;
See #5478.
Scoped enums
C++0x scoped enums are not documented as enum class.
See #5479.
Defaulted and Deleted Constructors
C++0x defaulted and deleted constructors are not documented as =default.
See #5480.
Guidelines
Documenting the Reference section following the C++ standard style
Doxygen provides a certain number of tags that allows to generate a clean documentation, but it would be great if all the Boost libraries document its Reference section following the C++ standard style.
Documenting typedefs
When the brief comment takes only one line the comment is included on the Synopsis and nothing on the description section
//! the underlying type typedef UT underlying_type;
generates
typedef UT underlying_type; // the underlying type
Steven Watanabe said: "This can be controlled by the BoostBook parameter, boost.compact.typedef."
Generating only one HTML page for the whole Reference
Steven Watanabe said: "You can use onehtml to generate a single html page. But I don't think this is as well tested as chunking though. I believe that the docbook stylesheets have a bunch of options that allow you to control chunking, too."
