- From: Max Polk <maxpolk@gmail.com>
- Date: Wed, 10 Jul 2013 08:51:46 -0400
- To: Julee <julee@adobe.com>
- Cc: PhistucK <phistuck@gmail.com>, Webplatform List <public-webplatform@w3.org>
- Message-ID: <CADPfvJtt3Pj7s48yRy1=xW0gr-E=nPPruHRKxgkKPcu8wTNZ+g@mail.gmail.com>
I now see PhistucK's point when I look at:
http://docs.webplatform.org/wiki/dom/objects/AnimationEvent
Inside the page it states that it inherits from Event and there's the link
right there to it. The Event page is not the parent of AnimationEvent,
it's a peer:
http://docs.webplatform.org/wiki/dom/objects/Event
In addition to the link, there is also an inline "Inherited from Event"
section where inherited Event info is shown, making the AnimationEvent page
a one-stop shop for everything you need without hunting backwards through
the inheritance chain.
This proves that we have precedent for a more flat structure among peers
situated under a few carefully selected parent pages, in this case,
dom/objects, dom/methods, dom/events, dom/properties, etc.
So at this point, we simply need to discover the best few, carefully
selected parent pages. A count of the original matter and their parent
pages are shown here:
1 Constants
2 Directives
3 Errors
1 Functions
1 Future Reserved Words
1 JavaScript Reference
1 Methods
336 Objects
39 Operators
1 Properties
1 Reserved Words
22 Statements
Obviously the big three are Objects, Operators, and Statements. If we
decide on only these three, that will knock out the majority of the
decision-making.
On Tue, Jul 9, 2013 at 2:21 PM, Julee <julee@adobe.com> wrote:
> To the main point of discussion: For the DOM, it makes sense to reflect
> the node hierarchy, because the coder is traversing the DOM. But what is
> the best way to describe the JavaScript language, itself, as the coder is
> working? In other words, the instance of an Array is based on changes to
> the prototype property of its constructors, but if there's a change to an
> existing object's prototype, it does not change the instance. So, I think I
> would usually want the current, enumerable properties (e.g.: Object.keys).
> That would mean I'd want the docs to reflect the Object inheritance.
>
> An aside: we discussed in an earlier thread that the convention we're
> using is lower case for general terms, and exact match for keywords, so
> Max, I would think your URIs would be either:
>
> ...objects/Array
>
> or
>
> ...Object/Array
>
> Regards.
>
> Julee
> ----------------------------
> julee@adobe.com
> @adobejulee
>
> From: PhistucK <phistuck@gmail.com>
> Date: Tuesday, July 9, 2013 8:09 AM
> To: Max Polk <maxpolk@gmail.com>
> Cc: Webplatform List <public-webplatform@w3.org>
> Subject: Re: JavaScript page naming, round B
>
> But our paths (so far, as far as I know) are not supposed to reflect
> prototype chains, but hierarchy.
> The prototype chain is reflected within the page of the object, by
> specifying that it inherits from Object (and others) and showing the
> methods of Object (and others) within it.
> See HTMLElement for example -
> http://docs.webplatform.org/wiki/dom/HTMLElement
>
> It shows members from HTMLElement, then from Element, then from Node. This
> is how we reflect the prototype chain,
> (Of course, every object inherits from Object and we should reflect that
> as well)
>
>
> ☆*PhistucK*
>
>
> On Tue, Jul 9, 2013 at 4:18 PM, Max Polk <maxpolk@gmail.com> wrote:
>
>> I'll restore what was lost and resend shortly.
>>
>> As to using Global, that feels like a mistake to me. Array or String and
>> so forth are Objects, because they point back to the Object prototype.
>>
>> The Object prototype (
>> http://www.ecma-international.org/ecma-262/5.1/#sec-15.2.4 ) has
>> important features that everything that derives from it (Array, String,
>> Number, etc) benefit. For example, because you know that Object has a
>> toString method you know that things that derive from it also have that
>> method available. You immediately know that on an Array you can call
>> toString.
>>
>> We don't document that Array has a toString method available in it,
>> because we know it derives from Object. So then if we take Object out of
>> the loop and use something like Global, we miss out on knowing the features
>> of Object we might want to use, such as these methods:
>>
>> js> [1, 2, 3].toString ()
>> 1,2,3
>> js> Number(123).valueOf ()
>> 123
>> js> [1, 2, 3].hasOwnProperty ("length")
>> true
>>
>> The prototype chain also shows that we can't kick Object out of the loop
>> when describing Array et al.:
>>
>> js> Object.prototype.isPrototypeOf (Array.prototype)
>> true
>> js> Array.prototype.isPrototypeOf (global.prototype)
>> false
>>
>> MDN calls them Objects (defined at global scope) then calls them
>> constructors: (
>> https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference#Global_Objects). ECMA calls them either constructors or type conversions (because not
>> using new acts like a type converter).
>>
>> The word "object" is used extensively across many languages. But in
>> JavaScript it has extremely precise meaning with important features. Here
>> it appears impossible to avoid it without losing information about the
>> prototype chain.
>>
>>
>> On Tue, Jul 9, 2013 at 1:35 AM, PhistucK <phistuck@gmail.com> wrote:
>>
>>> Thank you!
>>>
>>> Why are all of these in the same level?
>>> Function (and other objects) should be under Global (in my opinion) and
>>> function (and other statements or operators) should be under language (or
>>> similar, or whatever it was before).
>>>
>>> I have not read any post by anyone that asked to remove the Statements
>>> or Operators levels, why was it done?
>>>
>>>
>>> ☆*PhistucK*
>>>
>>>
>>> On Tue, Jul 9, 2013 at 4:53 AM, Max Polk <maxpolk@gmail.com> wrote:
>>>
>>>> This concerns the JavaScript page import effort.
>>>>
>>>> At the moment the Objects, Operators, and Statements pages with all
>>>> their subpages are being discussed.
>>>>
>>>> So far I have the following numbered steps, based on all the
>>>> accumulated suggestions so far.
>>>>
>>>> 1. REMOVE pages due to being Internet Explorer only.
>>>>
>>>> The list of pages to remove follow. Note that the "Statements/if" is
>>>> removed because it's a conditional compilation page for IE only. The
>>>> "Statements/if else" is the normal if statement.
>>>>
>>>> * Objects/ActiveXObject
>>>> * Objects/Enumerator
>>>> * Objects/Enumerator/atEnd Method
>>>> * Objects/Enumerator/item Method
>>>> * Objects/Enumerator/moveFirst Method
>>>> * Objects/Enumerator/moveNext Method
>>>> * Objects/Date/getVarDate Method
>>>> * Objects/Debug
>>>> * Objects/Debug/Debug.debuggerEnabled Property
>>>> * Objects/Debug/Debug.setNonUserCodeExceptions Property
>>>> * Objects/Debug/Debug.write Function
>>>> * Objects/Debug/Debug.writeln Function
>>>> * Objects/VBArray
>>>> * Objects/VBArray/dimensions Method
>>>> * Objects/VBArray/getItem Method
>>>> * Objects/VBArray/lbound Method
>>>> * Objects/VBArray/toArray Method
>>>> * Objects/VBArray/ubound Method
>>>> * Objects/WinRTError
>>>> * Statements/cc on
>>>> * Statements/if
>>>> * Statements/set
>>>>
>>>> 2. REMOVE from the page name the prefix "Objects", "Operators", or
>>>> "Statements".
>>>>
>>>> After removal and sorting the top level pages are as follows. Note
>>>> that there is one page name conflict, the function statement and the
>>>> Function object will both have the same page name "function" (or "Function"
>>>> but equivalent in the wiki, so they are in conflict).
>>>>
>>>> * Addition (operator) eg: x + y
>>>> * Addition Assignment (operator) eg: a += 5
>>>> * arguments (object) eg: arguments.length
>>>> * Array
>>>> * ArrayBuffer
>>>> * Assignment (operator) eg: x = y
>>>> * Bitwise AND (operator) eg: x & y
>>>> * Bitwise AND Assignment (operator) eg: x &= 2
>>>> * Bitwise Left Shift
>>>> * Bitwise NOT
>>>> * Bitwise OR
>>>> * Bitwise OR Assignment
>>>> * Bitwise Right Shift
>>>> * Bitwise XOR
>>>> * Bitwise XOR Assignment
>>>> * Boolean
>>>> * break (statement)
>>>> * Comma (operator) eg: x, y
>>>> * Comment
>>>> * Comparison
>>>> * Compound Assignment
>>>> * Conditional Ternary
>>>> * continue
>>>> * DataView
>>>> * Date
>>>> * debugger
>>>> * delete
>>>> * Division
>>>> * Division Assignment
>>>> * do while
>>>> * Error
>>>> * Float32Array
>>>> * Float64Array
>>>> * for
>>>> * for in
>>>> * function (statement)
>>>> * Function (object)
>>>> * Global
>>>> * if else
>>>> * in
>>>> * Increment and Decrement
>>>> * instanceof
>>>> * Int16Array
>>>> * Int32Array
>>>> * Int8Array
>>>> * JSON
>>>> * Labeled
>>>> * Left Shift Assignment
>>>> * Logical AND
>>>> * Logical NOT
>>>> * Logical OR
>>>> * Math
>>>> * Modulus
>>>> * Modulus Assignment
>>>> * Multiplication
>>>> * Multiplication Assignment
>>>> * new
>>>> * Number
>>>> * Object
>>>> * RegExp
>>>> * Regular Expression
>>>> * return
>>>> * Right Shift Assignment
>>>> * String
>>>> * Subtraction
>>>> * Subtraction Assignment
>>>> * switch
>>>> * this
>>>> * throw
>>>> * try catch finally
>>>> * typeof
>>>> * Uint16Array
>>>> * Uint32Array
>>>> * Uint8Array
>>>> * Unsigned Right Shift
>>>> * Unsigned Right Shift Assignment
>>>> * var
>>>> * void
>>>> * while
>>>> * with
>>>>
>>>> The action item for now is to decide if we like the above, and how to
>>>> resolve the one page name conflict for the "function" page.
>>>>
>>>
>>>
>>
>
Received on Wednesday, 10 July 2013 12:52:17 UTC