[[PageOutline]]

'''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 [mailto:boost-AT-lists.boost.org] and [mailto: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."