Using HTML tags in PHPDoc blocks

June 25, 2008 on 7:14 am | In PHP | |

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.

Tags: , ,

8 Comments »

RSS feed for comments on this post. TrackBack URI

  1. Hi Scott,

    The phpDocumentor manual covers that here [1]. There’s a core set of HTML tags that it recognizes in a docblock and assumes that you’re using them for formatting, not as literals. HTML tags that are not in that list will be treated a literal text regardless.

    That last point is good to know in case you’re stuggling with “<>” being interpreted literally as “<>” while “<>” is being interpreted correctly as “” as expected.

    [1] http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.desc

    Comment by Chuck Burgess — June 25, 2008 #

  2. Hmmm, my literal tags in my comment show up as empty tags :(

    Comment by Chuck Burgess — June 25, 2008 #

  3. Will use spaces inside the literal tags, to see if that works…

    The 2nd paragraph in my first comment should read:

    That last point is good to know in case you’re struggline with ” < > ” being interpreted literally as ” < > ” while ” < > ” is being interpreted correctly as ” ” as expected.

    Comment by Chuck Burgess — June 25, 2008 #

  4. Good grief, it did it again… ok, underscores this time…

    That last point is good to know in case you’re struggling with “<__>” being interpreted literally as “<__>” while “<__>” is being interpreted as expected as “”.

    Comment by Chuck Burgess — June 25, 2008 #

  5. Hmmm, I can’t win :(

    Ok, my first tag is supposed to be a “body” tag, while the second is a “b” bold tag. The “body” tag is not one that phpDocumentor looks for, while the “bold” tag is…

    Comment by Chuck Burgess — June 25, 2008 #

  6. Lol! Having fun? Thanks for your input though. Your problems here are kind of similar to the ones I was having with talking about tags in comment blocks. The page in the manual showed the double < <>> could be used for b, but it was pre and br I was trying to put in comments and < <>> seemed to work there too.

    Comment by Scott — June 25, 2008 #

  7. Ah, I see now. The manual uses “b” as an example, but I can see now how that wording could come across as “b” being the only <<>&gt case that’s available…

    Comment by Chuck Burgess — June 25, 2008 #

  8. Yep, but I got there in the end. Thanks for the heads up!

    Comment by Scott — June 25, 2008 #

Leave a comment

XHTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Entries and comments feeds. Valid XHTML and CSS. ^Top^
32 queries. 0.515 seconds.
Powered by WordPress.