Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.javascript > #14428

Re: Matt's DOM Utils (Utils): Alpha Release

Show all headers | View raw

On 12-06-06 10:14 PM, Andrew Poulos wrote:
> I want to make a comment on the documentation. I like having an
> example with each method so I'm sure how its meant to be called.

Understood. The problem with this idea is that each public
property will require its own page to expound upon its
purpose. When a project is sufficiently large (PHP), one page
per public property *with comments* works. In other cases
(jQuery), it bogs down the project.

My goal with the documentation for *Utils* is to make
each page (the entire project site, really) mobile-friendly.
Adding an example to each public property would surely
encumber the documentation. Currently, only public properties
that form the "dynamic interface" have examples (as part
of a warning).

However, I am working on a HOWTO section which will provide
in-depth tutorials and information; more will come after the
beta release. I'm lucky that I have so much free time on
my hands because they're exhausting.

One implicit purpose of *Utils* is to encourage one to
learn while interacting with it; too many DOM libraries
coddle developers. The expected parameter types are
intentionally vague to boost flexibility. When an
"array-like object" is specified, it means that anything
that passes `Utils.is.arrayLike` gets used (examples of
"false positives" would include Text nodes and String
objects). I even link "foreign" types to their corresponding
entries in the Glossary page. Moreover, the code itself
contains an exhaustive amount of documentation. Every
single function is documented.

I don't put on a sorcerer's hat to turn
`getElementsByTagName("*")` into a dove. Nor do I defer
to `document.all` like David Mark does. I just wrap the method,
then check the parameters and expect one to learn right
from wrong. That's the only way that developers are going to
improve. Half a decade of coddling hasn't helped.

-- 
Matt McDonald: Web/Flash Developer; Edmonton, Alberta, Canada

Back to comp.lang.javascript | Previous | Next — Previous in thread | Find similar | Unroll thread

Thread

Matt's DOM Utils (Utils): Alpha Release Matt McDonald <matt@fortybelow.ca> - 2012-06-06 21:53 -0600
  Re: Matt's DOM Utils (Utils): Alpha Release Andrew Poulos <ap_prog@hotmail.com> - 2012-06-07 14:14 +1000
    Re: Matt's DOM Utils (Utils): Alpha Release Matt McDonald <matt@fortybelow.ca> - 2012-06-09 17:36 -0600

csiph-web