michelf/php-markdown — pull request #100 by itafroma (2013-05-14 03:40:59+00:00)
Title: Convert public member comments to PHPDoc format

This is the promised pull request discussed in #98. This may be largely academic and not worth merging, however. It turns out there is [a PSR draft proposal](https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md) being worked out by the phpDocumentor team which may be worth adopting instead whenever it becomes a full PSR.

It's been in development for a couple of years now with no ETA on even a proposal, but it is intended to obsolete the PHPDoc "de-facto" standard, there's been some movement on the FIG side to get a documentation standard going, and it seems likely that the FIG will eventually adopt a documentation standard within the coming months.

So, given the timeline of removing legacy bits of Markdown that would prevent a wholesale conversion of all the comments, it may be worth postponing this entirely to see what the FIG does in the meantime.

All that said, I still created the PR for informational purposes and a jumping off point for discussions about how best to convert the comments whether it's done now or after a PSR emerges.

As suggested, only comments on public members were converted. I interpreted that as follows:

- The file-level comments were converted over. I couldn't find any guidance on how to handle multiple, disparate copyright tags, so the use of parens to denote John Gruber's copyright claim is definitely malleable.

- The class-level comments for `Markdown`, `MarkdownExtra`, and `_MarkdownExtra_TmpImpl` were converted over. The first two are uncontroversial. I converted `_MarkdownExtra_Tmplmpl` because, while an internal class, it contained public members. I marked it with the `@internal` tag to help avoid ambiguity by people relying on IDEs and such to determine what's usable.

- The `MARKDOWNLIB_VERSION` constant was converted over.

- The constructor comments were converted over under the premise that they are technically public method, even if their usage is either unnecessary or self-documenting due to lack of parameters.

- I made the call to convert the comments within public methods over as well. My reasoning for this was to avoid mixing commenting styles within a single logical block, but I'm not wedded to it.

- Where I saw an opportunity, I removed phrases or sentences that duplicated a tag. An example is changing *Change to `true` to disallow markup or entities* to simply *Disallow markup* because the `@var boolean` tag indicates the allowed values.

As an aside, in writing this, it was—for lack of a better word—weird to have two styles of commenting mixed together in the same file. Barring the PSR issue, that alone may be worth postponing this issue until everything can be converted over.