[glmdev]

I also think "adoptability" should be a consideration. Perhaps AsciiDoc would be a slightly better fit, but every developer I know is already familiar with MarkDown and at the end of the day convincing people to write good docblocks is easier if they don't have to pick up new syntax.

[eadler]

I can't stand both writing and reading markdown and find its use painful. While HTML isn't the nicest at least it has (a) separate markup and content and (b) predictable output.