[Bug 25303] New: Small bugs in the descriptions

https://www.w3.org/Bugs/Public/show_bug.cgi?id=25303

            Bug ID: 25303
           Summary: Small bugs in the descriptions
           Product: WebAppsWG
           Version: unspecified
          Hardware: PC
                OS: Windows NT
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DOM Parsing and Serialization
          Assignee: [email protected]
          Reporter: [email protected]
        QA Contact: [email protected]
                CC: [email protected], [email protected]

Hi, I gathered together a few minor bugs:

-----------
https://dvcs.w3.org/hg/innerhtml/raw-file/tip/index.html#dfn-dom-element-insertadjacenthtml
Algorithm for insertAdjacentHTML(position, text) method, step 3:

[3. Let fragment be the result of invoking the fragment parsing
algorithm with text as markup, and parent as the context element.]

We have "parent" but don't know what exactly it is. We jump to other algo
(parameter is context element).

-----------
https://dvcs.w3.org/hg/innerhtml/raw-file/tip/index.html#h3_parsing
In Parsing, first line we have:

[The following steps form the fragment parsing algorithm, whose
arguments are a markup string and a context element.]

Dot (.) at the end should be replaced by a colon (:).

And the same for:
[The following steps form the fragment serializing algorithm, whose arguments
are a Node node and a flag require well-formed.]


In the same Parsing algo, but step 5:
[5. Append each node in new children to fragment (in order).]

and some other place (like "XML serialization algorithm", "produce a
DocumentType serialization", "record the namespace information")

"in order" should be replaced by "tree order" and linked to DOM spec:
http://dom.spec.whatwg.org/#concept-tree-order. This term is used in
DOM and HTML5 spec.[1]

-----------
DOM in some IDL fragment use extended attributes (like [NewObject] and
[SameObject]):

[Constructor]
interface Document : Node {
 [NewObject] DocumentFragment createDocumentFragment();
}

So, you can do the same for some method:

[Constructor]
interface DOMParser {
    [NewObject] Document parseFromString (DOMString str, SupportedType type);
};

partial interface Range {
 [NewObject] DocumentFragment createContextualFragment(DOMString fragment);
};

-----------
https://dvcs.w3.org/hg/innerhtml/raw-file/tip/index.html#widl-DOMParser-parseFromString-Document-DOMString-str-SupportedType-type
In parseFromString method step 2:

[2. If the previous step didn't return an error, return the newly
created document and terminate these steps.]

Phrase "and terminate these steps" can be omitted because term
"return/throw" is unambiguous (leave algorithm). This convention is used in
DOM spec.

The same in outerHTML step 3:
[3. If parent is a Document, throw a NoModificationAllowedError
exception and terminate these steps.]

and insertAdjacentHTML step 1:
[1....If context is null or a document, throw a
NoModificationAllowedError and terminate these steps....]

So when we return something or throw error writing "terminate these
steps" is unnecessary. Link to changelog in DOM about this:
https://github.com/whatwg/dom/commit/d621e7e595e05808c6c54ea1cf4930cbfcc6316b

-----------
In DOM all error names are written in quotes, so in this spec you can
do similarly:

NoModificationAllowedError =>  "NoModificationAllowedError"
SyntaxError => "SyntaxError"

and all other case. This names may be linked exactly to some place in error
names table (http://dom.spec.whatwg.org/#error-names-0) << ale names have
id.[1]

-----------
https://dvcs.w3.org/hg/innerhtml/raw-file/tip/index.html#h2_extensions-to-the-range-interface
In chapter "8 Extensions to the Range interface", we have this code in green
box:

fragment = range . createContextualFragment(fragment)

Will be better if use "var" at the beginning and different name for
the variable and argument, now we have "fragment". Just something like
this:

var documentFragment = range . createContextualFragment(fragment)

or without "var" but different name.

-----------
Probably I will fine more small things but first I must jump from WHATWG spec (
continuously developed?) to W3C.

[1] Of course all suggestions linking to a new DOM can be make for W3C spec
version.

-- 
You are receiving this mail because:
You are on the CC list for the bug.