Re: Missing Essentials

On Sat, Oct 20, 2012 at 6:44 PM, PhistucK <phistuck@gmail.com> wrote:

> I am currently going through the various articles, cleaning up content and
> creating missing articles and I find a few essential things that are
> missing in or from the templates (or missing templates).
>

Awesome!  I'm so glad to see you participating in WPD. :-)

 This is a partial list. I will keep on posting updates when I find new
> essentials.
>
> I will be glad to help set these up, of course. If this is feasible, any
> guidance would be very much appreciated.
>

You should check out
http://docs.webplatform.org/wiki/WPD:Implementation_Patterns to get a very
high-level sense of how we've implemented stuff. I'm looking forward to
having more people know how to work within templates/ forms.

>
> 1. A template for constructors, with the ability to set a constructor as
> 'non constructible' (which essentially makes it an interface, rather than a
> constructor, but it is still a type), for things like HTMLElement, Window
> and other constructors that emit the "Illegal constructor" error message
> when, for example, new Window() is entered.
> Currently http://docs.webplatform.org/wiki/apis/xhr/objects/XMLHttpRequestis using a simple text to show the constructor syntax, but there should be
> a unified template for constructors/interfaces.
>

I think this makes sense. Are you proposing a template that would be
included within the content of  other page types?

>
> 2. The ability to specify multiple "Applies to..." values.
> This is useful for the "name" property (and others, like "pathname" and
> other URL decomposition properties that apply to several
> objects/interfaces/classes as well), since it exists on certain HTML
> elements (but not all) according to the specifications and you cannot
> subclass them to an imaginary element (HTMLElementWithName ;)), because
> that would just be... wrong(?).
>

This is something I've been meaning to do. It should just require a bit of
ArrayMap usage in the templates.

>
> 3. More types in the return value and parameter types.
> Basically, anything with the constructor template should be a type.
> This arbitrary basic selection box just does not quite cut it.
>

I added a link in the form UI next to that section to describe how to add
more types. Basically just add it to
http://docs.webplatform.org/wiki/Property:Javascript_data_type .

>
> 4. A constructor template for DOM properties, I guess.
> Example -
> There is the XMLHttpRequest object -
> http://docs.webplatform.org/wiki/apis/xhr/objects/XMLHttpRequest
> And then there is the XMLHttpRequest Window property -
> http://docs.webplatform.org/wiki/apis/xhr/properties/XMLHttpRequest
> That type of the property should be XMLHttpRequest and it should be a
> constructor.
> The current example shows var xhr = window.XMLHttpRequest, which is not
> how you would really use it.
> Perhaps the property page should just be removed, I am not sure.
>

Perhaps we should add it as an option on the property, which will allow the
syntax block example to automatically be generated with the right syntax.

>
> 5. Not specifying a "Subclass of" value for dom/ articles, automatically
> assumes dom/Element, which is incorrect.
> A lof of a dom/ articles do not talk about Element subclasses.
>

Do you have any example of one that shouldn't use that?


>
> 6. The CSSOM property template should automatically get its value(s) from
> its CSS property counterpart.
> If that does not happen, every value has to be updated twice - once for
> the font-weight and once for fontWeight.
> I doubt everyone (anyone?) will remember that.
>

Are you saying that that field on the CSS Property template should
automatically be generated based on a transform of the name of the
property? I agree we should, but I don't know what magic parser
functions/processing we'd have to do to make that work in mediawiki markup.

>
>
> Additional discussions -
> 7. I created the EventTarget API object -
> http://docs.webplatform.org/wiki/apis/EventTarget
> However, I am pretty sure I created in the wrong place and it might even
> not supposed to even exist in the documentation, since it might be just an
> implementation detail of some sort (there is no EventTarget under Window
> when checking with Google Chrome).
> I had to create it (or something along these lines), because a lot (or
> more than one, anyway) of interfaces subclass it, like Node, Document,
> Window.
> Any suggestions?
>

This is an interesting case. I think it does make sense to have, but
perhaps in the dom/ URL structure (as in, a sibling of Element).

>
> 8. Related to 1, 7 - should there be articles for the Document (not
> document) and Window (not window) intefaces?
> I guess there should be a dom/interfaces (maybe not only DOM ones, though)
> sub topic.
> HTMLElement, Document, Window and the rest of the interfaces would just go
> into it.
>

Is there a reason to have a separate interface article when the interface
is only implemented by one object?



By the way, these are great, very in-depth questions that demonstrate a
very deep understanding of some of the complex and arbitrary pieces in the
site.


>
> ☆*PhistucK*
>
>