[Bug 25565] New: [DOM-P&S] Another small bugs

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

            Bug ID: 25565
           Summary: [DOM-P&S] Another small bugs
           Product: WebAppsWG
           Version: unspecified
          Hardware: PC
                OS: Windows NT
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DOM Parsing and Serialization
          Assignee: travil@microsoft.com
          Reporter: crimsteam@gmail.com
        QA Contact: public-webapps-bugzilla@w3.org
                CC: mike@w3.org, www-dom@w3.org

Hello, I collect a next small bugs and other suggestions in this spec. Not
everything, others I will put in a new place, so let's start.

===

4.1 Parsing

You can join steps 2. and 3. for shorter algo and better clarity:

2. Invoke algorithm with markup as the input, and context element as the
context element.
3. Let new children be the nodes returned.

to

2. Let new children be the result of invoking the algorithm with markup as the
input, and context element as the context element.

We have this shorter convention in innerHTML/outerHTML algo (when setting).

===

4.2 Serializing

XML serialization algorithm >> Element

6. Let map be a copy of the prefix map namespace prefix map. << "namespace
prefix map" is unnecessary, we see what "prefix map" is in prose "To run the
XML serialization algorithm on..."

13.3.1. Let qualified name be the concatenation of candidate prefix, ":"
(U+003A COLON), and localName. << should be "node's localName" (see 12.3)
13.4.3. Let qualified name be the concatenation of prefix, ":" (U+003A COLON),
and localName. << should be "node's localName" (see 12.3)


XML serialization algorithm >> Text

6. Return data. << not "data", but "markup"


In the same chapter but a little higher:

[Initialize the namespace prefix map with the XML namespace key and string
"xml" as the key value.] << String [xml] should be outsied "" (as in all
similar cases).

[Elements not in the HTML namespace containing no children, are serialized
using the self-closing tag syntax (i.e., according to the EmptyElemTag
production of [XML10]).] << "EmptyElemTag" should be surrounded by <code>, not
<var> (as in all similar cases). Also string "children" may be linked to DOM
def (as in all similar cases "children/child").

===

6.1 Methods

[The serializeToString(root) method must produce an XML serialization of root
passing...] << For "serializeToString(root)" we don't have id, all other
methods/attributes have id in this place.

===

7.1 Attributes [outerHTML on getting]

We have:

[On getting, return the result of invoking the fragment serializing algorithm
on a fictional node whose only child is the context object context object
providing true for the require well-formed flag (this might throw an exception
instead of returning a string).] << unnecessary repetition "context object
context object", should be only "context object".

===

7.2 Methods

Algo insertAdjacentHTML, step 1:

Otherwise
    [Throw a SyntaxError exception.] << Maybe better to write [Throw a
DOMException with name "SyntaxError"]? And "SyntaxError" can be linked to DOM
table.

Btw, Firefox and Chrome for this exception use DOMException, but IE use Error.

===

8.1 Methods [createContextualFragment]

1. Let node the context object's start node. << "Let node be the..."

===

When you list concatenation of strings we have two conventions:

1. "</" (U+003C LESS-THAN SIGN, U+002F SOLIDUS);
2. The value of qualified name;
3. ">" (U+003E GREATER-THAN SIGN).

vs.

1. " " (U+0020 SPACE);
2. The string "SYSTEM";

Sometimes in the last step you used "." but sometimes ";". Probably should be
"." in every cases.

===

XML serialization algorithm >> Element, step:
13.4.5.2. the string "xmlns:"; << start with "The" (as in all similar cases).
13.4.3.5. the value of prefix; << start with "The" (as in all similar cases).
13.5.5.2. the string "xmlns"; << start with "The" (as in all similar cases).

===

XML serialization of the attributes, step:
3.5.3.2. Append the following to result: << better is "Append the following to
result, in the order listed:" (as in all similar cases).
3.9. Append the following strings to result: << better is "Append the following
to result, in the order listed:" (as in all similar cases).

===

In algo:

- "record the namespace information" (step 2.3.1)
- "XML serialization of the attributes" (step 3.5.1)

we stop running step, will be better if mark where we back, sth like we have in
DOM (http://dom.spec.whatwg.org/#concept-traverse-children).

===

When refer to DOM for name exception will be better if you refer exactly to
this error name, not just table (all errors in table have id). When we jump to
this table we see 21 name (now) and don't remember what error we click:) Small
upgrade, but this style is used in DOM spec and it's helpful (we get exactly
row of this exception).

===

No big problem, but when use extended attributes in IDL maybe better write them
in one line (only for attribute/method, not constructor):

[NewObject] Document parseFromString (DOMString str, SupportedType type);
[NewObject] DocumentFragment createContextualFragment (DOMString fragment);

[TreatNullAs=EmptyString] attribute DOMString innerHTML;
[TreatNullAs=EmptyString] attribute DOMString outerHTML;

We save some lines:), but in fact this convention is used in other spec., like
DOM and HTML5.

===

I see some inconsistency when use variables in the algorithms. Look (var is
marked by []):

Return the value of [serialized document].
Return [data].
Return [markup].
Return the value of [markup].
Return [document].
Return [fragment node].

Let [ns] be the value of [node]'s namespaceURI attribute.
Let [qualified name] be the [node]'s localName.
Let [markup] be [node]'s data.

etc.

Sometimes using "value of", but sometimes missing, even in similar (the same)
cases. A consistent style would be advisable.

=== 

Uff finish, would be nice if any of my suggestions will be useful. To the next
bugs...

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

Received on Tuesday, 6 May 2014 00:57:35 UTC