[meta] Consistency In API

[ptwobrussell]

From ptwobrussell:

As I'm writing this book on Dojo, I'm looking at the totality of the toolkit from an API-centric point of view (especially Base) and am noticing (fairly minor) inconsistencies that we may want to consider "fixing". For example:

• In html.js, most functions from this family accept either a string id or a dom node as a first param, but a few (like hasClass, addClass, etc.) accept only a dom node and fail if you accidentally (because you're generalizing your knowledge from other functions) pass in an id value. So there's the size (extra dojo.byId call) vs consistency vs performance vs breakage considerations in dealing with fixing something like this.

• In other places, params to families of functions are named different things, so it would be nice to name params consistently across the board so that the "family" relationship might be even more apparent, so that your doc tools produce a nice consistent API, etc. (things like obj vs thisObject vs o as param names, for example.)

In either of these cases, I'd be happy to generate the patches since I'm _almost_ generating them anyway as I sift through all of these things in my writing efforts. However, in that first issue especially, it seems as though there would need to be a little pow-wow to get to some final decision.

[bill]

Names

Well, I think we'd appreciate patches for standardizing naming of positional parameters and types (like "DomNode?" vs. "HtmlElement?"), although I remember endless debates about abbreviations vs. spelled out names (spelled out names sound good until you get tired of typing "replaceVariables" instead of "replaceVars"). As for named parameters like in

  new dijit.form.Button({ label: "hi" })

etc. changing those would mean an API change which would inconvenience our current users, so that's got pros and cons.

Dual ID vs Node arguments

This was also the topic of much debate, as it trades off convenience for efficiency and code size. I think the conclusion was to only make really common functions take an id or a node, but to make uncommon functions just take a node. So it's by design, and I'd hate to beat that dead horse again.

[alex]

(In [11038]) make sure we're accepting string args for the dojo.*Class methods. Refs #4580

[ptwobrussell]

Sweet. so that takes care of #1. Once I have the Base API (function signatures and identifying comments for parameters) in a nice standardized format for the book, I'll get back in touch about sync'ing it up with the code base via some patches.

[alex]

(In [11040]) HTMLElement -> DomNode? in docs. Refs #4580

[alex]

(In [11041]) updating docs to note string args. Refs #4580. Thanks to ptwobrussell and phiggins for staying on me about it = )

[bill]

See [11043]

[alex]

I think we're in better shape on this for now, but since ptwobrussell hasn't submitted a detailed list or patches, I'm gonna have to punt this ticket to 1.1

[alex]

marking this "[meta]". We need concrete things to fix in the comments (many of the originally listed problems are solved).