Source code docs: down with javadoc, up with markdown!

Good documentation doesn’t come easy. Documenting source code is rarely something a coder likes to do. I’m just as guilty as anyone else. I know it’s a “good thing”, but my natural inclination is to code first and document later. Sometimes later comes so late that it’s a chore to get it done. I’ve been forcing myself to document as I go, and it usually works out pretty well in the end.

I’m a control freak

What’s made this process easier for me is to completely dump the notion of auto-generated documentation (I’m looking at you, javadoc, jsdoc, yuidoc, ruby-doc and the like). Instead, I favor writing the documentation for a given piece of code with markdown.

It’s a tradeoff between automation and control, and when it comes to documentation, I prefer the control.

I can start by documenting only that


Turtle Wax: LOGO-style graphics re-imagined for JavaScript and HTML5 Canvas

I was feeling nostalgic over the holidays, and extolling the virtues of one of the first languages I enjoyed as a kid: LOGO. Then I dug back into the syntax of LOGO. Compared to modern programming languages, words like “terse” and “arcane” spring to mind.

I decided I wasn’t that nostalgic after all, but I did want to bring some of the cool graphics capabilities of that venerable language to JavaScript.

Instead of making a LOGO interpreter in JavaScript (it’s been done), I made a small API to achieve turtle graphics in a more familiar setting.

Check out a couple code demos

Be sure to view source on these pages:

Spirograph inspired designs

Fractal trees translated from a LOGO example

How it works

The API attaches itself to a canvas tag, and supports chaining. I also decided to add some convenient methods for more traditional cartesian and polar coordinate systems.

More info can be found at the project


Adventures with Microsoft’s IE9 Preview

Ok, I’ve been keeping an eye on this, and with the recent preview 6, there are still some big missing pieces in their CSS3 support:

  • CSS3 gradients
  • Flexible box model
  • Text shadow

Plus, on the JavaScript side, I have yet to be able to get any CSS transforms working, though the way to detect them seems to be:

if ( !== 'undefined')  

In short, it seems to have relative parity with Opera 10 as far as cool-yet-useful CSS3 features. Keep going, Microsoft, I’m totally cheering for you!


Tip: faster mousemove events in webOS 1.4.5

Warning: this is a short-term solution, it may cause interesting results in future versions of the webOS SDK, so use wisely.

One minor frustration I’ve run into with making JavaScript webOS apps (games in particular) is the mousemove events don’t seem to fire very often on custom controls. This is particularly noticeable when users finger-paint on canvas tags or drag elements around. I suspect that this quirk in the webOS webkit was introduced as a performance improvement, but running up against it can be painful.

A fix I’ve discovered is this simple CSS addition to any elements which need higher resolution mouse movement (er, touch movement, whichever):

myelement {  
    -webkit-user-drag: element;

Just put any valid CSS selector in place of “myelement” above, and you should notice a marked improvement in mouse movement precision for the element(s) in question.

This is not a future-proof solution, because if Palm


Jo cross-platform demo screencast up on YouTube

Twelve minutes of Jo, showing the same JavaScript web app code running on webOS, iPhone, iPad, Android, Symbian and... Dashboard widgets? Yup.

First in a series of videos, this screencast is a quick intro to the cross-platform capabilities of this JavaScript framework (both for mobile apps with PhoneGap and mobile web apps). Followup videos will cover making your first Jo app, getting it running with PhoneGap, theming it with CSS and other goodies. Enjoy!

You can also read more about this open source project at