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

On Jun 7, 2007, at 3:57 PM, Norman Walsh wrote:

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

The Java code used  are generated from an XML interface definition  
language which defines methods and attributes and is the basis for  
both the recommendation text and the published bindings.  The get and  
setDocumentURI methods are the transliteration of the documentURI  
attribute into Java and, as you inferred, the documentation of the  
attribute is copied to both the get and set methods.  There is not  
any support in the recommendation language for distinct text for  
getting and setting an attribute or any other implementation language  
specific renderings.  The duplicate text is an artifact of the  
process and not easily changed.  Errata typically one tweak some  
aspect of the abstract language and the abstract language in the  
recommendation is fine.