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."