PalmSource was once known for their next-to-perfect API documentation. Failures, bugs, hints and other useful stuff were contained right in the Palm OS API documentation. However, as PalmSource staff got less, the quality of the documentation decreased according to developer’s oppinion(I still consider it useful btw – so this is no rant).

Anyways, while coding a little PHP script, I needed help about a call and looked at the official PHP documentation:

http://at.php.net/str_split

I quickly found out that the function I needed wasn’t available in the PHP version that our current host(HostLoco) runs. However, the comments contained like 15 ready-to-use replacement functions and hints on usage!

The PHP API documentation system has two parts – the first part is ‘fixed’; and the second part consists of comments like we have it at TamsPalm’s. So, vandals cant change the core documentation, but users can add hints easily.

IMHO, PalmSource should convert its Developer’s API Reference to this format if they somehow can…developers would greatly benefit from the extra amount of knowledge available!

What do you think?

Related posts:

  1. Android documentation – Plucker friendly
  2. ZLauncher Plug-In API for OnBoardC
  3. Multitasking with non-cobalt PalmOS
  4. OnBoardC and the glue library – changing control attributes
  5. Palm OS and Linux

2 Responses to “Self improving API documentation”

  1. It is a good idea, but the thing is that PalmSource is basically dead. PalmSource now only really exists (in effect) as a name assosiated with Access. As a result, the old docs will probably go without serious official maintenence.

    Hopefully (big big big hope) Palm Inc itself will release its own new OS as rumored and with it will maintain the old API/Style and write new docs for it.

  2. When I was at PalmSource, the PHP “docs w/ comments” model was something many of us really wanted to implement. However, reworking the docs from their Framemaker source into something that could be put into a database plus doing the web-side of things was beyond what the little DTS group could do at that time. While I’m not in the DTS group at Palm, I know the people in that group, and during next time I talk to them, I’ll mention this as something they should model as they’re reworking the whole PluggedIn site to be more open and accesible.

Leave a Reply

(required)

(required)

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Subscribe without commenting

© 2013 TamsPalm - the Palm OS / web OS Blog Suffusion theme by Sayontan Sinha