Opened 12 years ago

Closed 8 years ago

Last modified 8 years ago

#4580 closed enhancement (fixed)

[meta] Consistency In API

Reported by: ptwobrussell Owned by: dylan
Priority: high Milestone: 1.7
Component: General Version: 0.9
Keywords: api, consistency Cc: ptwobrussell@…
Blocked By: Blocking:

Description (last modified by bill)

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.

Change History (15)

comment:1 Changed 12 years ago by James Burke

Milestone: 1.0
Owner: changed from anonymous to alex

comment:2 Changed 12 years ago by 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.

comment:3 Changed 12 years ago by ptwobrussell

Cc: ptwobrussell@… added
Reporter: changed from guest to ptwobrussell

comment:4 Changed 12 years ago by alex

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

comment:5 Changed 12 years ago by 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.

comment:6 Changed 12 years ago by alex

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

comment:7 Changed 12 years ago by alex

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

comment:8 Changed 12 years ago by bill

See [11043]

comment:9 Changed 12 years ago by alex

Milestone: 1.01.1
Status: newassigned

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

comment:10 Changed 12 years ago by dylan

Milestone: 1.11.2

comment:11 Changed 12 years ago by alex

Summary: Consistency In API[meta] Consistency In API

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

comment:12 Changed 11 years ago by bill

Description: modified (diff)
Milestone: 1.2future

comment:13 Changed 8 years ago by Chris Mitchell

Owner: changed from alex to dylan
Status: assignednew

comment:14 Changed 8 years ago by dylan

Resolution: fixed
Status: newclosed

comment:15 Changed 8 years ago by bill

Milestone: future1.7
Note: See TracTickets for help on using tickets.