W3C home > Mailing lists > Public > public-webplatform@w3.org > November 2013

Re: JS content plan

From: Max Polk <maxpolk@gmail.com>
Date: Sun, 17 Nov 2013 15:35:00 -0500
Message-ID: <CADPfvJvkiNRtvxBk2J_tH47+1ASBVqJTy1WUGQFNr_+NSB1Edw@mail.gmail.com>
To: WebPlatform Public List <public-webplatform@w3.org>
Here is a summary of all comments so far and an attempt to address each one
as an indented reply.

It looks like we can accomodate all the input so far.

--------------------
Rick Byers

slight preference for omitting the suffixes ('Property' etc.)
... they'll almost always be obvious from the context.

    DONE.  See "removing the Objects part from the path"
    section below, removed both prefix and suffix.  However,
    see "unclear which was a static Array" section below
    for why we can't remove Method versus Function
    suffix.

is there a separate effort to document the DOM APIs?

    YES, it's in the wiki/apis directory.  This keeps the
    apis separate from the language.  I just sent an email
    to the list saying let's keep libraries separate from
    APIs as well and to put that into wiki/libraries.

Are you planning on having any sort of 'browser compatibility'
table?

    PROBABLY.  We could easily address this by adding a
    good semantic form field for it that renders special.


links to the authoritative source (specs, etc.)

    WISE.  We could add another semantic form field that
    links to the ECMA site page that gives the official
    definition.

--------------------
Rick Waldron

removing the "Objects" part from the path, since
that's implicit

    The top level is mostly objects, operators, and statements:
        Operators/Addition Assignment
        Statements/continue
        Objects/Uint16Array
    Mashing up all Objects at the top level is unambiguous,
    as long as we keep the Operators/ and Statements/ prefix.

    Example including removing suffix is now:

    Array                      [formerly Objects/Array]
    Array/concat               [formerly Objects/Array/concat Method]
    Array/length               [formerly Objects/Array/length Property]
    Regular Expression         [formerly Objects/Regular Expression]
    String/trim                [formerly Objects/String/trim Method]
    Uint16Array                [formerly Objects/Uint16Array]
    Operators/Logical NOT      [keep the prefix for Operators]
    Operators/Modulus          [ " ]
    Statements/this            [keep the prefix for Statements]
    Statements/throw           [ " ]
    Constants                  [single page for all constants]
    Reserved Words             [single page for all reserved words]

unclear which was a static Array "class-side" method or a
method of Array instances, ie. Array.prototype

    This is dealt with so far by using a suffix.  We use
    method for instance methods (need an instance to call it)
    versus function for static class functions (use class name
    to call it).  For example, page names are:

    Array/isArray Function      [ Array.isArray (...)  ]
    Array/concat Method         [ a.concat (b)         ]

    If we remove the suffix (see above request to remove suffixes)
    the developer won't know how to write code, so we either use
    a path like prototype (let's not), or a simple suffix "Function"
    versus "Method" (let's do).
Received on Sunday, 17 November 2013 20:35:28 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:13:55 UTC