Re: get/setDocumentURI in org.w3c.dom.Document

/ Bjoern Hoehrmann <derhoermi@gmx.net> was heard to say:
| * Norman Walsh wrote:
|>The JavaDoc for get/setDocumentURI (and a number of other methods) in
|>org.w3c.dom.Document are clearly broken.
|>
|>See, for example:
|>
|>  http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Document.html#getDocumentURI()
|>
|>and
|>
|>  http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/Document.html#setDocumentURI(java.lang.String)
|>
|>
|>Is there any chance these have been/will be fixed by an erratum?
|
| Those are HTML documents presumably created by Sun, we have no control
| over them. If you could explain what you think should be changed in the
| http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/ Java binding
| files, it might be possible to fix them. At the moment I am not even
| sure what you think is broken in those HTML documents.

Bjoern,

Yes, it's true that those are HTML files created by Sun. They were
created by running the distributed Java binding API files through the
JavaDoc compiler. It was convenient to point to them because the W3C
doesn't seem to provide the JavaDoc online. I didn't imagine that
anyone would suspect that Sun did any more or less than publish the
documentation provided in the distributed APIs.[*]

Consider the Java API bindings distributed at

  http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/java-binding.zip

In Document.java, we find, among other things:

    /**
     *  The location of the document or <code>null</code> if undefined or if 
     * the <code>Document</code> was created using 
     * <code>DOMImplementation.createDocument</code>. No lexical checking is 
     * performed when setting this attribute; this could result in a 
     * <code>null</code> value returned when using <code>Node.baseURI</code>
     * . 
     * <br> Beware that when the <code>Document</code> supports the feature 
     * "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML</a>]
     * , the href attribute of the HTML BASE element takes precedence over 
     * this attribute when computing <code>Node.baseURI</code>. 
     * @since DOM Level 3
     */

    public String getDocumentURI();
    /**
     *  The location of the document or <code>null</code> if undefined or if 
     * the <code>Document</code> was created using 
     * <code>DOMImplementation.createDocument</code>. No lexical checking is 
     * performed when setting this attribute; this could result in a 
     * <code>null</code> value returned when using <code>Node.baseURI</code>
     * . 
     * <br> Beware that when the <code>Document</code> supports the feature 
     * "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML</a>]
     * , the href attribute of the HTML BASE element takes precedence over 
     * this attribute when computing <code>Node.baseURI</code>. 
     * @since DOM Level 3
     */
    public void setDocumentURI(String documentURI);

As far as I can tell, something about the process that generated those
API files caused the documentation for each get* method to be
textually identical to each set* method. Is that not a bug?

It is, at the very least, confusing to speak of "setting this
attribute" in the documentation for the get* method. And it was, in
fact, misleading to at least one user of the APIs.

                                        Be seeing you,
                                          norm

[*] Although I put up considerable resistance, I was eventually
persuaded to make very small changes to the APIs in order to fix
broken JavaDoc coding and the occasional typo. I believe that I have
also reported each of those errors, though I don't have pointers
handy.

-- 
Norman Walsh <ndw@nwalsh.com> | Linux. Because rebooting is for
http://nwalsh.com/            | hardware upgrades.