Re: [PATCH] Several patches to improve libstdc++ API docs

[Jonathan Wakely <jwakely at redhat dot com>]

On 02/05/19 16:47 +0100, Jonathan Wakely wrote:
> I've just committed a series of patches to improve the organization
> and formatting of the Doxygen-generated API documentation.
>
> - Update libstdc++ Doxygen config
> - Adjust Doxygen processing of pb_ds containers
> - Fix markup for Parallel Mode docs
> - Improve Doxygen docs for nested namespaces
> - Improve API docs for mathematical special functions
> - Improve API docs for <memory> and <scoped_allocator>
> - Improve docs for Filesystem TS
> - Improve docs for Library Fundamentals TS
> - Improve docs for Networking TS
> - Improve docs for C++17 Filesystem library
> - Improve docs for mutexes
> - Allow Markdown formatting in Doxygen comments
> - Miscellaneous API doc improvements
>
> The patch is large so I've bzipped it, but it's almost entirely
> changes to comments, with a couple of small re-arrangements of code to
> improve the generated HTML docs.
>
> Committed to trunk.
>
> More changes coming soon too (including enabling Doxygen processing
> for the C++17 components).

Some things worth calling out specifically from this series of
patches:

* Markdown is enabled in doxygen comments now. That might mess
existing comments up, where underscores in type names get interpreted
as markdown. I'll try to review the existing docs for that, and escape
things with backslashes, or surround them with backticks if that's
more appropriate.

* I've made extensive use of @relates (aka @related) to group things
like operator== and operator!= with the class they belong to.

* I've started using Doxygen's @cond command to mark things that we
don't want to document, because they're not meant to be user-visible
e.g.

 /// @cond undocumented

 template<typename _Tp>
   struct __some_internal_helper
   { };

 /// @endcond

If the "undocumented" tag is set in the ENABLE_SECTIONS config in the
doc/doxygen/user.cfg.in file then these sections will still be
processed by doxygen. That means maintainers who want to generate full
docs can still do so, but the default won't include the @cond stuff.

* I've just realized I committed this chunk, which was unintentional:

+# ifdef _GLIBCXX_DOXYGEN
+    /// Windows uses wchar_t for path::value_type, POSIX uses char.
+    using value_type = __os_dependent__;
+# else
+    using value_type =  char;
+# endif

Since I didn't commit a change to actually defined _GLIBCXX_DOXYGEN,
that serves no purpose.

* Currently no C++17 or Networking TS headers are processed by
Doxygen. I'm doing to change that soon.