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

Re: JS content plan

From: PhistucK <phistuck@gmail.com>
Date: Sun, 17 Nov 2013 23:11:25 +0200
Message-ID: <CABc02_KL+iFzPi-ipPmNZ9QV6HzWk25P=MjQtwNDP-9vWEySug@mail.gmail.com>
To: Max Polk <maxpolk@gmail.com>
Cc: WebPlatform Public List <public-webplatform@w3.org>
I am stongly against the suffixes. Static or non static, we do not need
them and it breaks consistency with the rest of the paths in other
namespaces (apis/, dom/ and similar APIs).
We should find a better way to reflect static versus instance, if such way
is needed at all.
I do not think it must be reflected in the path. The content of the page
itself can reflect that instead. This way has the benefit of making it
easier to get to other methods by simply manually changing the path when
you search for stuff (I know I use the address bar a lot in these types of
references).
(And again, if it must be in the path, any static property or method must
have these in the path in other namespaces)

Also, "Regular Expressions" should be under Syntax or something, RegExp is
the underlying object for Regular Expression literals. Object and Array
literals have no pages of their own, apparently, so maybe Regular
Expressions literals should not have one as well.

I keep seeing pages that are non standard and Microsoft specific, like
VBArray, GetObject, ActiveXObject and some more - the mapping for these
should be "dropped" or something, as they should not be imported at all.

Thank you very much!


☆*PhistucK*


On Sun, Nov 17, 2013 at 10:35 PM, Max Polk <maxpolk@gmail.com> wrote:

> 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 21:12:32 UTC

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