Scott’s Spiel

As I mentioned in my last WordPress post I’ve been working on adding documentation to the core of WordPress, specifically the formatting.php file. This is quite a big file will upwards of 2000 lines of code and around 65 functions to document. It is used extensively in the formatting of pretty much every aspect of a blog. It surprised me therefore that when I started getting involved in developing WordPress this file (with the exception of may a dozen functions) completely lacked documentation.

Over the past number of weeks I’ve been (rather slowly, it’s quite a boring process) adding inline documentation to the file. So far I’ve got around 70-80% of the file done and plan on doing as much of the rest that I can. Unfortunately some of the functions are a bit difficult for me to understand and, at the risk of writing totally incorrect documentation, I’ve been leaving these.

However there is only one other developer actively documenting the code. New code is being documented as it is written but there is a great deal of code lacking any. Hopefully the 2.7 release will see a good deal more added. My contributions have already been committed to the Subversion trunk which I’m quite happy about.

As my involvement in the dev side of WordPress grows, I’ve been working on increasing the PHPDoc comments through the major parts of the code. A particular challenge I stumbled across today was trying to talk about certain HTML tags in the comments in a way that they wouldn’t then be turned into the actual tag when phpDocumentor ran.

So basically I wanted to say something like

This function returns a properly formatted <pre>…</pre> block

However I found that doing that caused the <pre> tag to be used as part of the page when the docs were transferred to the HTML format.

The solution I discovered was to reference the tags as <<pre>> or <<br />>. This seems to preserve the tag in the finished documentation as a comment and not part of the page.

I struggled to find this in google, so though a little blog post might just help someone.