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.
Loading ...
8 COMMENTS
Posted on June 25th, 2008 at 5:53 pm by Chuck Burgess
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
Posted on June 25th, 2008 at 5:55 pm by Chuck Burgess
Hmmm, my literal tags in my comment show up as empty tags
Posted on June 25th, 2008 at 5:57 pm by Chuck Burgess
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.
Posted on June 25th, 2008 at 5:59 pm by Chuck Burgess
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 “”.
Posted on June 25th, 2008 at 6:00 pm by Chuck Burgess
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…
Posted on June 25th, 2008 at 6:09 pm by Scott
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.
Posted on June 25th, 2008 at 6:27 pm by Chuck Burgess
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 <<>> case that’s available…
Posted on June 25th, 2008 at 6:35 pm by Scott
Yep, but I got there in the end. Thanks for the heads up!
LEAVE A COMMENT