Re: Clarification needed regarding default value of newLine in DOMSerializer of DOM L3 LS spec

On Thu, 2003-11-06 at 17:06, Ramesh Babu Mandava wrote:
> Hi:
>    
>  Java binding of DOM L3 LS at
> 
> http://www.w3.org/TR/2003/WD-DOM-Level-3-LS-20030619/
> 
> contain unclear javadoc for getNewLine and setNewLine methods of DOMSerializer class. 

First, the documentation is written from the point of view of the
specification, not from the javadoc. The javadoc is generated as a
convenience in the Java interfaces, but the DOM script that generates
the interface cannot produces different text for each setter and getter
in the Javadoc.

>  From the javadoc it is not clear that what should getNewLine return in case setNewLine is not called before ( default value ). Whether "null" should be returned or the "platform default end-of-line sequence"?  

The CR version of the specification does say:
[[
The default value for this attribute is null.
]]
http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/load-save.html#LS-LSSerializer-newLine

>  The javadoc for setNewLine is exactly same as getNewLine?

Generated automatically from the specification. It is the case for all
DOM attributes.

>  There is need for changing the javadoc for getNewLine and setNewLine and make it different to define specific purpose of each method.

Doing so would require changing the way the specification is being
produced (using xmlspec for the moment). I can try to write the text so
that it is comprehensible when you read from a setNewLine() or
getNewLine() javadoc point of view but making the attribute texts
specific for their setter and their getter would require more work than
I am willing to spend on it now. Core and LS contain 100 attributes.

>  Whether the intention is that when "null" value is
> passed to setNewLine, then the end-of-line sequence   
>  need to be defaulted to platform specific one? And
>  getNewLine should never return "null"

Agreed. We changed the description to get the default value
(implementation specific end-of-line sequence) on retrieval, and on
setting,  use the value null to set it to its default value.

Philippe

Received on Monday, 5 January 2004 15:39:28 UTC