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

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

[giecrilj at stegny dot 2a.pl]

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

             Bug #: 50143
           Summary: Doxygen API documentation is invalid
    Classification: Unclassified
           Product: gcc
           Version: 4.5.1
               URL: http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen
                    /a01566.html
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: libstdc++
        AssignedTo: unassigned@gcc.gnu.org
        ReportedBy: giecrilj@stegny.2a.pl


Submit that page to the WWW HTML validator, and the result is:

Validation Output: 5819 Errors
Line 63, Column 4: document type does not allow element "li" here; missing one
of "ul", "ol", "menu", "dir" start-tag

(and 5818 errors follow)

Wow!

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

[paolo.carlini at oracle dot com]

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

--- Comment #1 from Paolo Carlini <paolo.carlini at oracle dot com> 2011-08-21 15:03:38 UTC ---
And the page has been *generated* by Doxygen (1.7.4, in particular), right? So,
why do you think that, if anything, this is a libstdc++ bug?!?

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

[giecrilj at stegny dot 2a.pl]

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.

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

[redi at gcc dot gnu.org]

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

--- Comment #3 from Jonathan Wakely <redi at gcc dot gnu.org> 2011-08-21 19:54:15 UTC ---
(In reply to comment #2)
> 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.

Yep

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

Yep.

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

Utter nonsense.

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

Of course building gcc isn't necessary to run doxygen.

This bug report is valid, but your argument is ridiculously overstated, let's
keep some sense of proportion.  The product being shipped is not "broken"
except in the most pedantic sense.

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

[paolo.carlini at oracle dot com]

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

--- Comment #4 from Paolo Carlini <paolo.carlini at oracle dot com> 2011-08-21 20:07:27 UTC ---
Bah, in my opinion, if Doxygen otherwise suits our needs we should just keep
using it and ask users interested in HTML Validator results to file PR with
Doxygen. But certainly I don't feel strongly about these issues.

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #5 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-21 20:41:56 UTC ---
Created attachment 25069
  --> http://gcc.gnu.org/bugzilla/attachment.cgi?id=25069
documentation screen shot

The documentation window contains two frames: the index frame and the content
frame.  The text in the content frame is obscured by the text in the index
frame even though the horizontal scrollbar in the content frame is in the
leftmost position (which is not immediately visible because of a bug in the
color scheme).  The documentation is unreadable.

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #6 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-21 20:45:29 UTC ---
(In reply to comment #3)
> Of course building gcc isn't necessary to run doxygen.
> 

I unpacked gcc and I said { make make doc-html-doxygen; }.
Make said "No such target."

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #7 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-21 20:49:10 UTC ---
(In reply to comment #4)
> Bah, in my opinion, if Doxygen otherwise suits our needs we should just keep
> using it and ask users interested in HTML Validator results to file PR with
> Doxygen. But certainly I don't feel strongly about these issues.

The problem with this approach is that it is not easy for a user to reproduce
the problem, let alone isolate some test case.

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

[paolo.carlini at oracle dot com]

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

--- Comment #8 from Paolo Carlini <paolo.carlini at oracle dot com> 2011-08-21 20:50:06 UTC ---
I don't know which browser you are using, but with Firefox 6 the documentation
is definitely readable. Also, I don't know if you are an HTML expert, I'm not,
but I would not be **so** sure that all the visualization problems you are
having are due to the html and not the browser and its rendering engine.

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #9 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-21 20:54:33 UTC ---
(In reply to comment #8)
> I don't know which browser you are using, but with Firefox 6 the documentation
> is definitely readable. 

Konqueror 4.6

> Also, I don't know if you are an HTML expert, I'm not,
> but I would not be **so** sure that all the visualization problems you are
> having are due to the html and not the browser and its rendering engine.

A browser bug against an invalid page will not be accepted.  It is undefined
behavior.

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

[dominiq at lps dot ens.fr]

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

--- Comment #10 from Dominique d'Humieres <dominiq at lps dot ens.fr> 2011-08-21 20:56:00 UTC ---
> I don't know which browser you are using, but with Firefox 6 the documentation
> is definitely readable.

This is the same with Safari. Note that on both Safari and Firefox, I first get
a widow as displayed in the attachment in comment #5 then the right pane is
redrawn in a legible way.

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

[paolo.carlini at oracle dot com]

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

--- Comment #11 from Paolo Carlini <paolo.carlini at oracle dot com> 2011-08-21 20:59:51 UTC ---
(In reply to comment #10)
> This is the same with Safari. Note that on both Safari and Firefox, I first get
> a widow as displayed in the attachment in comment #5 then the right pane is
> redrawn in a legible way.

Doesn't happen here. Anyway, I still believe that a sensible way to go is
filing a Bug Report with Doxygen. In terms of Bug Reports. Or, make a
convincing case that another tool is **overall** preferable to Doxygen. I don't
think this kind of technical discussion really belongs here.

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

[paolo.carlini at oracle dot com]

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

--- Comment #12 from Paolo Carlini <paolo.carlini at oracle dot com> 2011-08-21 21:04:06 UTC ---
By the way, I just tried Safari 5.1 and it also works fine for me (as long as
the above link and a few others are concerned, at least)

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #13 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-21 21:05:11 UTC ---
(In reply to comment #11)
> Doesn't happen here. Anyway, I still believe that a sensible way to go is
> filing a Bug Report with Doxygen. 

Apparently.  However, the problem is I cannot do it myself without isolating a
test case, and that requires reproducing the build, and that is I do not know
how to do.

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

[redi at gcc dot gnu.org]

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

--- Comment #14 from Jonathan Wakely <redi at gcc dot gnu.org> 2011-08-21 21:26:02 UTC ---
fine, I'll reproduce it and report a bug to Doxygen

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

[paolo.carlini at oracle dot com]

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

--- Comment #15 from Paolo Carlini <paolo.carlini at oracle dot com> 2011-08-21 21:48:14 UTC ---
If you can Jon, it would be great. I tried with the browsers I have at hand to
no avail, so far. Anyway, if trustworthy html validators report errors for the
pages generated by Doxygen, the developers should at least explain that (but
frankly, as I tried to explain already, I have no idea if those are really
serious or not and could explain serious visualization problems in some cases)

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

[joseph at codesourcery dot com]

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

--- Comment #16 from joseph at codesourcery dot com <joseph at codesourcery dot com> 2011-08-22 13:22:55 UTC ---
On Sun, 21 Aug 2011, giecrilj at stegny dot 2a.pl wrote:

> > Also, I don't know if you are an HTML expert, I'm not,
> > but I would not be **so** sure that all the visualization problems you are
> > having are due to the html and not the browser and its rendering engine.
> 
> A browser bug against an invalid page will not be accepted.  It is undefined
> behavior.

HTML5 specifies exactly how invalid documents must be parsed (to avoid 
security issues with different user-agents parsing the same document 
differently, I think).

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

[redi at gcc dot gnu.org]

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

--- Comment #17 from Jonathan Wakely <redi at gcc dot gnu.org> 2011-08-22 14:27:13 UTC ---
reported upstream https://bugzilla.gnome.org/show_bug.cgi?id=657081

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

[redi at gcc dot gnu.org]

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

Jonathan Wakely <redi at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |RESOLVED
         Resolution|                            |INVALID

--- Comment #18 from Jonathan Wakely <redi at gcc dot gnu.org> 2011-08-22 14:39:01 UTC ---
the konqueror rendering problem is NOT caused by the invalid XHTML.

Using the source code and doxygen config in my doxygen bug report, I changed
HTML_ALIGN_MEMBERS=YES and added GENERATE_TREEVIEW=YES

That produces valid XHTML, but konqueror still can't display it correctly, it
puts the main page body under thee left-hand menu tree

I don't think there's much we can do in libstdc++ about this

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #19 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-22 19:03:13 UTC ---
(In reply to comment #16)
> HTML5 specifies exactly how invalid documents must be parsed (to avoid 
> security issues with different user-agents parsing the same document 
> differently, I think).

The Doxygen output is in HTML4.

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #20 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-22 19:04:50 UTC ---
(In reply to comment #18)
> the konqueror rendering problem is NOT caused by the invalid XHTML.
> 
> Using the source code and doxygen config in my doxygen bug report, I changed
> HTML_ALIGN_MEMBERS=YES and added GENERATE_TREEVIEW=YES
> 
> That produces valid XHTML, but konqueror still can't display it correctly, it
> puts the main page body under thee left-hand menu tree
> 
> I don't think there's much we can do in libstdc++ about this

Please publish your result (just one page will do).

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

[redi at gcc dot gnu.org]

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

--- Comment #21 from Jonathan Wakely <redi at gcc dot gnu.org> 2011-08-22 19:08:26 UTC ---
(In reply to comment #19)
> The Doxygen output is in HTML4.

No, it's XHTML 1.0

(In reply to comment #20)
> Please publish your result (just one page will do).

I've deleted it now, you can see for yourself using the (about 10 lines in
total) examples in my doxygen bug report

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #22 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-30 13:10:38 UTC ---
(In reply to comment #21)
> (In reply to comment #20)
> > Please publish your result (just one page will do).
> 
> I've deleted it now, you can see for yourself using the (about 10 lines in
> total) examples in my doxygen bug report

The result of the bug, html/namespacefoo.html, is perfectly legible in
Konqueror, so I still cannot reproduce (a valid unreadable document is needed).

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

[redi at gcc dot gnu.org]

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

--- Comment #23 from Jonathan Wakely <redi at gcc dot gnu.org> 2011-08-30 13:25:17 UTC ---
Did you alter the Doxyfile as I described in Comment 20 here?  Otherwise you're
not getting valid XHTML, and you're not getting the treeview that caused the
problem when I tested it.

I've reported the doxygen bug, I've shown you how to run doxygen. I've
described how to change the Doxyfile to avoid the bug, I've tested it in
Konqueror, so far all you've done is ask me to do everything, even when it only
involves running three simple shell commands.  I have better things to do. Feel
free to debug it and suggest fixes yourself, but don't expect me to spend any
more time showing you how to run doxygen etc.

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

[redi at gcc dot gnu.org]

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

--- Comment #24 from Jonathan Wakely <redi at gcc dot gnu.org> 2011-08-30 13:27:37 UTC ---
(In reply to comment #23)
> Did you alter the Doxyfile as I described in Comment 20 here? 

Comment 18, rather

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

[giecrilj at stegny dot 2a.pl]

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

--- Comment #25 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> 2011-08-30 13:51:39 UTC ---
Well, the original documentation now shows up in Konqueror after a little
delay, so the original failure might have been due do a network problem (e.g. a
failed script download).  While it is bad design to rely on scripts to make a
page readable, it is obviously not your problem.  Thanks for your help anyway.