[Bug 25303] Small bugs in the descriptions

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

--- Comment #3 from Travis Leithead [MSFT] <travil@microsoft.com> ---
(In reply to spiritRKS1910 from comment #0)
> 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).

I think "parent" is supposed to be "context". Context gets the parent under
some of the conditions in step 1.


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

Good catch.


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

Sounds good. I counted 14 occurrences of "in order" but many of these are
referring to following a sequence of steps in order. Two require a link to
DOM's "attribute list" concept. I'll fix-up the prose to make all occurrences
more clear.

> -----------
> 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);
> };

Super. Will do.

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

OK. After removing this phrase it only occurs once in the conformance section,
and once in an algorithm which does not involve a return/throw condition.
Thanks for the pointer.


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

Nice cross-linking. Sounds good.


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

Agree that this explanatory usage isn't as good as it could be. I'll change the
name of the variable receiving the return value and the parameter to be less
ambiguous.

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

Thanks

-- 
You are receiving this mail because:
You are the QA Contact for the bug.

Received on Thursday, 17 April 2014 17:19:15 UTC