[Bug libstdc++/50143] Doxygen API documentation is invalid

["giecrilj at stegny dot 2a.pl" <gcc-bugzilla@gcc.gnu.org>]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=50143

--- Comment #2 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-21 19:33:07 UTC ---
Please tell me if you find the following argument invalid:

  1. 
It is the responsibility of the library to provide API documentation for the
developers using the library.

  2. 
The library can provide the documentation in whatever way it seems fit,
provided that the documentation is readable and meets its essential purpose.

  3.
The library documentation provided with the library is unreadable.

Conclusion: the library failed to provide appropriate documentation.  Ergo, it
is the library‘s fault.  

The user is not interested in what particular tool the library manufacturer
internally uses, as long as it works.  The user is not in position to tell
whether the fault is in Doxygen markup or in Doxygen engine; in either case,
the user is not in position to fix the documentation so as to make it useful.

If you feel that this is Doxygen‘s fault, you, as the manufacturer, have the
following options:

  * 
Diagnose the problem, file a bug at Doxygen and hope it will get fixed.

  * 
Use some other tool to generate API documentation.

  * 
Do nothing, and continue to ship a broken product pretending it is not your
fault.

The choice is yours.  

I would be happy to be able to reproduce this Doxygen problem and isolate a
reportable test case; however, I am not sure I know how to do it.  It seems
building gcc first is necessary, and it is quite a job.