php-markdown
php-markdown copied to clipboard
michelf
Adopt PHPdoc-style commenting
To help with IDE integration, provide an easy way to generate API documentation, and generally conform better with how many other PHP projects are commented, I'd like to propose that Markdown adopt PHPDoc-style tags and C-style comments.
Namely, this would entail adopting the following tags:
and converting the Perl-style # comments to // for single line commends and
/**
*
*/
for comment blocks.
I'm willing to submit a pull request for this, but it's a fair amount of work and I'd like to see if you'd be amenable to what will amount to a pretty drastic change to how the lib is commented.
Actually I'd rather have this issue open than #2, since this one is more focused only on documentation comments and is more detailed.
As I said in #2, I'm open to it. Here's my suggestion: do it only for documentation comments of public members (methods and variables) and the class itself. The benefit for public members is much greater (protected members are only meant for tinkering with the parser, which not many people do and the API for that is not considered stable). There's also the issue that I'm still keeping in sync the master and extra branches, and changing comments everywhere would make merges difficult (unless we backport the changes to these branches too). I'll be much more amendable to global changes in style once I drop support for master and extra (next year).
Sounds fair. Just so I'm clear, are you suggesting that:
- just PHPDoc-style tags be added for the public members/class, keeping the Perl-style comments intact globally; or
- convert the comments on the public members/class over entirely to C-style comments using PHPDoc tags, creating a mix of Perl-style and C-style comments; or
- Convert everything to C-style comments, but only add PHPDoc tags to the public members/class?
That's a good point about the other branches. Would you accept a PR to backport whichever the strategies above are used, or would you rather wait until those branches are dropped?
I was thinking about 2. After that let's evaluate whether 3 is worth the trouble while the other two branches are still maintained.
By the way, if we restrict ourself to 2 I don't think it needs to be back-ported. The idea is that it touches things which are mostly different in the other branches and it won't create an extra burden for merges. For the few things in common (configuration variables), they change rarely and it probably won't create much conflicts.