Update libstdc++ Doxygen config
authorJonathan Wakely <jwakely@redhat.com>
Thu, 2 May 2019 15:44:16 +0000 (16:44 +0100)
committerJonathan Wakely <redi@gcc.gnu.org>
Thu, 2 May 2019 15:44:16 +0000 (16:44 +0100)
commitacd482ba727dc8257324c9ab29f82321a1e8da29
tree3ea4f83c191c4f5c5b23f8307c5ccb5ad77ce79d
parentfb2c78f8aa4d14cc8d5e2ddda4d50d24ddc1dba0
Update libstdc++ Doxygen config

The GROUP_NESTED_COMPOUNDS option means that types nested inside inline
namespaces or other classes will be automatically added to a Doxygen
group, e.g. this actually works as intended:

  /**
   * @defgroup chrono Time
   * @ingroup utilities
   *
   * Classes and functions for time.
   * @{
   */

  namespace chrono
  {
    template<typename _Rep, typename _Period = ratio<1>>
      struct duration;

    template<typename _Clock, typename _Dur = typename _Clock::duration>
      struct time_point;
  }

  /// @}

Currently chrono::duration and chrono::time_point are not added to the
"chrono" group. They would need an explicit @ingroup tag added to them
individually. With GROUP_NESTED_COMPOUNDS=YES they get added to the
enclosing group.

The SORT_BY_SCOPE_NAME option means that the list of classes will sort
by class name, not the full qualified-id. Currently the alphabetical
Class List for classes beginning with 'c' looks like:

  char_traits (__gnu_cxx)
  character (__gnu_cxx)
  condition_base (__gnu_cxx)
  const_iterator_
  condition_variable_any (std::_V2)
  cauchy_distribution (std)
  char_traits (std)

i.e. the list is sorted by the namespaces first, then the class names.
This is not helpful when you don't know which namespace a class might be
in, and inline namespaces with reserved names are not hidden (see
https://github.com/doxygen/doxygen/issues/5914 for a feature request to
allow that).

With SORT_BY_SCOPE_NAME=NO the list looks like:

  cauchy_distribution (std)
  char_traits (__gnu_cxx)
  char_traits (std)
  character (__gnu_cxx)
  condition_base (__gnu_cxx)
  condition_variable_any (std::_V2)
  const_iterator_

This allows you to find a class by name more easily.

Also add PREDEFINED macros so that __attribute__ and various macros like
_GLIBCXX_NO_DISCARD, _GLIBCXX14_CONSTEXPR don't appear in the generated
docs.

* doc/doxygen/user.cfg.in: Regenerate with Doxygen 1.8.14 and set
GROUP_NESTED_COMPOUNDS=YES and SORT_BY_SCOPE_NAME=NO. Add various
_GLIBCXX_xxx macros and __attribute__(X) to PREDEFINED macros that
Doxygen expands.

From-SVN: r270802
libstdc++-v3/ChangeLog
libstdc++-v3/doc/doxygen/user.cfg.in