W3C home > Mailing lists > Public > www-dom@w3.org > April to June 2001

Re: Java doc bugs

From: Philippe Le Hegaret <plh@w3.org>
Date: Thu, 21 Jun 2001 17:51:41 -0400
Message-ID: <3B326C6D.83071FE0@w3.org>
To: Edwin Goei <Edwin.Goei@eng.sun.com>
Cc: www-dom@w3.org, Jamie Ho <Jamie.Ho@Sun.COM>
Edwin Goei wrote:
> 
> Philippe Le Hegaret wrote:
> >
> > Here is a new try:
> > http://www.w3.org/2001/06/java-binding.2.zip
> >
> > Since the Java sources are generated, I had to change the DOM scripts
> > to generate the documentation of Node.
> > It fixed the same problem in the Document interface (createElementNS,
> > createAttributeNS). Also, the description of importNode wasn't
> > "well-formed".
> 
> Thanks, it looks better.  From a quick scan, I've noticed these items:
> 
>   + The url href mentioned in more than one file does not exist:
>     http://www.w3.org/2001/04/WD-DOM-Level-2-Core-20010417

I was using the editors work version of the DOM Level 2 sources to generate
the bindings. I'll make sure to use the REC version to generate the
final version for the erratum.

>   + It looks like the get/setXXX() methods have the same javadoc, which
> may be suboptimal b/c for example, Attr#getValue() says it can throw a
> NO_MODIFICATION_ALLOWED_ERR while the DOM spec says that only the
> Attr#setValue() method should do this.  In addition, the other javadoc
> comments may sound somewhat awkward.  Since it sounds like you are
> auto-generating the java bindings, it may be difficult to fix this.  So,
> I will leave it up to you as to whether it is worth fixing this to avoid
> user complaints.

Yes. Unfortunately, the XML sources don't contain enough meta informations
to know if an exception should be generated or not. I think it's better to
have this solution than having no documentation at all.

We should probably fix that in DOM Level 3 but it means modifying the
xmlspec DTD...

Thank you for your report,

Philippe
Received on Thursday, 21 June 2001 17:51:42 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Friday, 22 June 2012 06:13:48 GMT