182177 - Comments in nsIXSLTProcessor.idl are incorrect

Status: VERIFIED FIXED

(Core :: XSLT, defect)

Description

[Michael Hearn]

Some of the comments are either incorrect or confusing as to what the methods do
and how to use them.

From importStylesheet(): 

   then the document can contain either a XSLT stylesheet
   or a LRE stylesheet.

An expansion of LRE would be nice here, it's result element transform right?

From transformToFragment(): 

   @param output The owner document of this node is used to generate the output

However, the output argument is itself a Document so saying "owner document of
this node" implies that it can be any node which is not the case. The argument
name output is also somewhat confusing....

The comments for transformToDocument() are just incorrect, they seem to be
copypasted from the previous definition.

Nitpicky I guess, but I'm currently writing some docs on this object so good
comments would be helpful ....

thanks -mike

Comment 1

[Jonas Sicking (:sicking) No longer reading bugmail consistently]

LRE stylesheets you can read in section 2.3 of the spec so i don't think they
need more explanation in the .idl.

Comment 2

[Jonas Sicking (:sicking) No longer reading bugmail consistently]

The Note in the comment for importStylesheet is wrong as well and should be removed

Comment 3

[Jonas Sicking (:sicking) No longer reading bugmail consistently]

Attachment: patch to fix

fixes the stuff mentioned in comment 0 and comment 2 and a few other errors.

Comment 4

[Axel Hecht]

Comment on attachment 114398 [details] [diff] [review]
patch to fix

>Index: public/nsIXSLTProcessor.idl
>===================================================================
>RCS file: /cvsroot/mozilla/content/xsl/public/nsIXSLTProcessor.idl,v
>retrieving revision 1.3
>diff -u -r1.3 nsIXSLTProcessor.idl
>--- public/nsIXSLTProcessor.idl	8 Nov 2002 08:50:33 -0000	1.3
>+++ public/nsIXSLTProcessor.idl	14 Feb 2003 04:01:23 -0000
<...>
>@@ -84,16 +78,16 @@
>      * importStylesheet() function.
>      *
>      * @param source The node to be transformed
>-     * @param output The owner document of this node is used to generate
>-     *               the output
>-     * @return DocumentFragment The result of the transformation
>+     * @return Document The result of the transformation
>      *
>      * @exception nsIXSLTException
>      */
>     nsIDOMDocument transformToDocument(in nsIDOMNode source);
> 
>     /**
>-     * Sets a parameter to be used in the following calls to transformNode.
>+     * Sets a parameter to be used in calls to transformToFragment and
>+     * transformToDocument. If the parameter doesn't exist in the stylesheet
>+     * the parameter will be ignored.
>      *
>      * @param namespaceURI The namespaceURI of the XSLT parameter
>      * @param localName    The local name of the XSLT parameter

Don't give the transformation methods names. We might add methods and I don't
feel like giving them all.
Something like "to be used in subsequent transformations with
this nsIXSLTProcessor" should do.
>@@ -107,7 +101,8 @@
>                       in nsIVariant value);
> 
>     /**
>-     * Gets a parameter, if set and return null otherwise.
>+     * Gets a parameter, if set and return null otherwise. If the parameter has
>+     * not been set by a call to setParameter null will be returned.
>      *
>      * @param namespaceURI The namespaceURI of the XSLT parameter
>      * @param localName    The local name of the XSLT parameter

You return null twice.
"Gets a parameter if previously set by setParameter and returns
null otherwise."? Note the "s" in "returns".
<...>

Other than that, fine with me.

Comment 5

[Jonas Sicking (:sicking) No longer reading bugmail consistently]

fixed locally

Comment 6

[Axel Hecht]

over to jonas

Comment 7

[Peter Van der Beken [:peterv]]

Comment on attachment 114398 [details] [diff] [review]
patch to fix

With Pike's changes.

Comment 8

[Jonas Sicking (:sicking) No longer reading bugmail consistently]

checked in

Comment 9

[Axel Hecht]

mass verifying