Re: Callability of <object> (was: Re: Array-with-item in WebIDL)

On 6/17/15, Boris Zbarsky <bzbarsky@mit.edu> wrote:
> On 6/17/15 10:48 AM, Garrett Smith wrote:

[...]

>> Most web developers don't read specs because the specs are
>> confusing.
>
> I agree that this is a problem.  The way to solve it is to have web
> developer facing documentation... but that documentation is likely to
> not mention legacy deprecated features in the first place.
>

This is a problem.

The HTML5 spec is *already* too long and verbose on the legacycaller
stuff and it didn't seem intuitive when I read it. Quite the opposite.
I did not see the link in the HTML5 spec to Cameron McCormack's github
pages for legacycaller and I would not have guessed to go there.

Two sets of documentation, where there is real documentation for you
and tutorial style docs for web devs (and member organizations)
doubles, at a minimum, the maintenance involved. Double confusion with
bug reports, two paths, two languages, more hidden internal methods
and disconnect between developers and implementors.

The real HTML5 spec would evolve as the ECMAScript spec has, with more
esoteria; more internal methods.

One set of documentation with ubiquitous language could eliminate
extraneity and lead to better understanding and communication (for bug
reports, web classes, etc). Think DRY for documentation. Two sets of
documentation would create multiple ways of perceiving one reality.

[...]

> You are of course free to not like my attitude, and I am free to
> reciprocate.  But I think in this case the spec makes the right call in
> not spending too much time discussing the intricate details of a
> deprecated feature.
>

The documentation on legacycaller is already long. Maybe too long.

The API design defines the functionalities available to programs and
it describes what the browser is supposed to do with those programs.
The API we are discussing includes legacy and new features.

It should now be clear what is meant by "API design".

The specification describes that design could be better. Shorter, more
concise, and clearer is better. It would be shorter and IMO clearer
like this:

| interface HTMLObjectElement : HTMLElement, Callable
|
| ...
| [deprecated_icon] "When called as a function… "
|
| . . . . . . . . . . . . . . . . . . . . [compat_table]
| . . . . . . . . . . . . . . . . . . . . [bugs_list]

In this hypothetical example, OBJECT implements Callable and HTMLElement.

That's an example of the Interface Segregation Principle (ISP). What's
wrong with that?
-- 
Garrett
@xkit
ChordCycles.wordpress.com
garretts.github.io
personx.tumblr.com

Received on Wednesday, 17 June 2015 17:05:51 UTC