Markdown Lists With ApiGen

I am using ApiGen to create API documentation for a PHP project I’m coding. Within comment blocks of documentation, so-called ‘docblocks’, you can use Markdown syntax. That made me happy because these days I use Markdown when writing pretty much anything—emails, this site, documentation, and so on.

But I ran into one problem with how ApiGen handles ordered lists, which is best explained with a long example.

All This For One Regular Expression…

You can create ordered lists in Markdown by numbering the items naturally, e.g. writing

1. This is the first item.

2. And the second.

3. And so on.

This works in ApiGen only if there is no line break. In other words, list items cannot span multiple lines. So I had a rather long comment block explaining each part of a regular expression where I originally tried to use the list format above. But ApiGen messed up as soon as it saw an item longer than one line and it only treated the first line as part of the list item. To get around that and get the proper formatting I had to wrap that list in some good ‘ole HTML tags. Here is the piece of code I’m referring to, in its entirety, since it has both list formats:

 * A regular expression which matches the format of KGS
 * usernames on their game archive page.  This matches the
 * name `Reimu[-]`, for example.  The regular expression
 * contains two capture groups:
 * 1. The username.
 * 2. The rank, without the square brackets.
 * These two groups are also accessible as named groups,
 * `username` and `rank`, respectively.  This regular
 * expression attempts as much as possible to conform to the
 * rules for acceptable KGS names and ranks.
 * The following is a break-down of the components of the
 * regular expression:
 * <ol>
 * <li>An anchor for the start of the string.</li>
 * <li>One to ten letters or numbers.  KGS only allows Roman
 * letters and imposes the limit of ten characters.  This part
 * is the `username` capture group.</li>
 * <li>Optional whitespace that can appear between the
 * player's name and the rank.</li>
 * <li>The start of a non-capture group for the square
 * brackets that can be the rank in a player name.  This
 * entire group is optional because guest accounts do not have
 * brackets.  This means that, as a whole, everything after
 * the two parts above is optional.</li>
 * <li>A literal opening square bracket for the start of the
 * rank section.</li>
 * <li>A dash, or zero to two digits followed by one of three
 * letters: `k`, `d`, and `p`.  All of this may have an
 * optional question mark at the end.  This entire part is a
 * capture group with the name `rank`.</li>
 * <li>A literal closing square bracket to end the rank.</li>
 * <li>An anchor for the end of the string.</li>
 * </ol>
 * The entire expression already has delimiters and so it can
 * be the pattern for functions such as `preg_match()` without
 * having to first surround the pattern in delimiters.
 * @var string
private static $player_regex = '/^(?P<username>[a-z0-9]{1,10})\s*(?:\[(?P<rank>-|(?:(?:\d{0,2}[kdp]{1})?)\??)\])?$/i';

Yeah, I know, fifty-two lines of documentation for one regular expression….

But anyways, if you have list items that span multiple lines then you need to resort to HTML tags. The first list in the comment produces the expected output because both items are on a single line. Most of the rest, however, are not and so they need the appropriate HTML tags.

Just a small something to look out for if lists in your output from ApiGen look strange.


Add Your Thoughts

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s