Saturday, October 16, 2010

Automatic API v3 reference

I have a test page that analyzes contents of google.maps namespace. I've had it for a long time. The trouble was that controlling the version needed some hackery with v3. Now when the version control was released, I decided to polish and share the page. Actually it is a site of three pages, one for each version. Frozen (3.0), Release (3.1) and Nightly (3.2).

API v2 is from 2005 and no namespace thinking was applied. The constructors and all the stuff that v2 offers is introduced in global scope. I never faced any troubles with that but nowadays some people like it as 'bad programming practice'. Actually it really was much trickier to write a similar test page for v2. Global scope (window) has a lot of stuff that is introduced by the browser and must be filtered.

The test page scans google.maps object by a for-in loop. No rubbish is found and no additional filtering is needed. The results contain the constructors and some objects. Those are listed on page and also on the index in the header. All the members that were found are scanned by a for-in loop again. This time looking inside prototype objects. If prototype is not found, the object itself is looped. Resulting properties are listed in a row.

The pages are coded for Firefox only. Firefox presents some unique features for this kind of work. One of them is .toSource() method of Object. It creates a string representation of source code. Firefox presents source code in nice prettyprinted format in alert() dialog box.

With Firefox, you can click any listed method on page and see its internal code. Also there are links to search the method name from documentation, API forum or Google Code Search.

The resulted listing proves that API v3 is written following good programming practices. Almost no internal variables are leaking. The internal source code of the constructors and their methods doesn't reveal much. Still it is worth exploring, you always find something that deepens your understanding about API.

The documentation practice of v3 is different to v2 in the way that there are not many undocumented methods in v3. Still you can find some. Today I saw some new methods of Marker.

You can use the pages for comparing versions. Yes, they are documented separately but still you can find something meaningful.

1 comment:

appleton said...

Neat!

I see that bindTo() and other inherited methods are documented on each class. You could use .hasOwnProperty() to strip those, and instanceof or .__proto__ to extract the inheritance hierarchy.

By the way, __gjsload__() is the public hook that JS modules use to hook into the API.