jQuery: API documentation /2

Still about improving the official documentation.
|modified content, my style – snapshot for jQuery $( String, Object )
|official content, my style – snapshot for jQuery $( String, Object )
|official content & stylesnapshot for jQuery $( String, Object )

Functionality VS function
As an example of something that needs a rewrite take the $ function, which accepts many inputs and mostly does one of two things: either selects a group of elements into a DOM (possibly all of them), or creates a group of elements from scratch.

In the official documentation these two functionalities are mixed up in the filecard with one string argument, whereas the selection functionality with a string argument is split among two filecards, depending on wether there is only one argument for the string or also a second argument for the context. In case of one argument, the functionality does not change because a default value is used for the context.

The signature of a function
A very good thing in the official documentation is the use of type declarations for functions and arguments. Javascript is loosely typed and this is just a handy trick. I think I found a problem related to how much it is used.

The name of a function cannot be adapted in the documentation to reflect its type, so a declaration like Array<Element> get() makes a lot of sense. A different approach is needed for an argument name, which certainly can get a new name in the documentation. For the sake of readers, the same pseudo types should be used as much as possible for arguments as well. In fact, if an argument can get different types without changing the functionality of the function, then it’s much better to use a generic Object type and add a comment than it is to use a more specifiic Element type just because it is the most frequent use of that argument. In the former case the reader gets a hint at a nuance to whatch out, in the latter they need to carefully read the filecard to get the nuance.

The pseudo signature of a function can be augmented also with default values for optional arguments, like other languages do. This improves the readability a bit more, because less words are needed in the documentation, as it is a visual device.

An id for each functionality
Having each functionality documented in its own filecard, a unique identifier for referencing them is then needed. For example, see also the code in 2 could be a short comment of an example in a filecard, where the reader can be made aware of watchouts related to that code. The longer see also the code in ‘jQuery $( String, Object )’ is more informative but would be harder to add in the source of jQuery and to create an hyperlink in the documentation. To implement: longer form automatically built from id

The benefits of an id for each functionality go well beyond that. When speaking or writing about jQuery functions, the use of an id could simplify the reference, though something like calling 32 from 154 causes 9 to hang should definitely be avoided, and for posterity is to be preferred something like (this purely fictitious) calling toggle (32) from oneunload (154) causes serialize (9) to hang (using Rev:123)

For a working sample, I’ve added an id attribute to the method element of the documentation XML. It’s now a decimal number, starting from 1, which I’ve assigned to the most used function of jQuery: jQuery $( String, Object ). For making straighforward the referencing in the documentation XML and hence in the js sources, you simply have to wrap a grave accent (`) around the id of a function, like see also the code in `2`. This works inside the description of a function or example, and inside the comment of an example.

jQuery: API documentation /1

jQuery is pure enjoyment: you try something and it works.

But the jQuery API documentation needs improvements on interface and content.

The interface is a bit annoying, because of the drawer metaphore. The user must always open a drawer to see what’s inside and close it again to tidy up.jquery2.png

This problem affects both the description of a function and the alphabetical grouping of all the functions. So each function description is actually hidden inside two drawers, one for the tab of the first letter of the function name, and the other for the fuction itself. A bit more complicated than it should be for browsing an API documentation.

Visual jQuery is a replacement of the official interface and content. It’s based on the drawer metaphore as well, but with a twist. The user, knowing what is looking for, imagines a path of predefined categories, and opens all of their drawers to get there. It’s less weird than it seems from this description, but there is some additional problem.

The header eats up almost an half of the vertical space, and it’s not very useful.visualjquery1.png

Scrolling the page down makes the content disappear under the header.visualjquery2.png

Any drawer appears at the top, so after opening a drawer at the bottom the user must scroll the page up to see its content.visualjquery3.png

Simple Style

I’ve just made yet another replacement of the jQuery API documentation.

It’s based on a two columns layout hosting a list of links on the left and the linked content on the right: basic web metaphore.simple_jquery1.png

It’s still far from completion. This is a partial list of what must be done.

  1. add alphabetical positioning for the links on the left; should be something similar to the original alphabetical tabs, just not tabs: clicking on a letter would cause the left pane to scroll
  2. make the functionality the main concept of the documentation and separate functionalities from functions, each in its own filing card: for example, “$( expr )” has now two different functionalities, so they should be represented by two separate filing cards;
  3. add a unique and persistent ID number to each functionality, so that they can be referenced from inside the documentation, and in the wild by means of a an URL ending with this ID; it would appear where now is a #
  4. check the description of any argument; should be very focused about what the function expects, how it’s related to the functionality
  5. add keywords to highlight documentation wide aspects; it would appear where now is the category; should be a comma separated list, with a fixed precedence
  6. check the description, and edit it thinking about the functionality, being very specific on what gets changed and what is returned
  7. find better and useful examples, always involving a DOM context that can be expressed by HTML markup, both in the Before and After sections.
  8. add a comment to a solution, relating it to “synonyms and antonyms”-like solutions
  9. developed at 1024×768 screen resolution using IE6: check others
  10. template adapted to CSS from one generated by Microsoft Word: refine

Tolerance to loss of connectivity when auto-refreshing a page

Refreshing content could be loaded in an invisible container and then copied to the visible one if it’s valid. The validity check could be in the content itself: a function call at the end of the body will do.

Prepare two containers for your content: VisibleContainer, and HiddenContainer. Define two global script functions: refreshVisible(), and refreshHidden().

refreshHidden()

  1. download fresh content to the HiddenContainer
  2. reset a timer for calling refreshHidden() after x seconds

refreshVisible()

  1. if not called from HiddenContainer then exit
  2. copy fresh content from HiddenContaner to VisibleContainer

Finally, call refreshHidden() from the onLoad event of VisibleContainer, and make a call to refreshVisible() from the very end of the content loaded in HiddenContainer.

If there is a loss of connectivity, then there is no call to refreshVisible(), and no error is shown. Also, the timer will continue to run and it will call refreshHidden() upon expiration.

(revised text from my own comment 12628152 at Experts-Exchange)