search

DevinVinson / WordPress-Plugin-Boilerplate

[WordPress] A foundation for WordPress Plugin Development that aims to provide a clear and consistent guide for building your plugins.
http://wppb.io
7.67k stars 2.25k forks source link

Page level documentation #46

Closed GaryJones closed 11 years ago

GaryJones commented 11 years ago

The page level documentation for the .php files could be improved. See https://github.com/GaryJones/visual-subtitle/blob/master/visual-subtitle.php as an example.

It contains the plugin name as the short description, followed by several useful phpDocumentor tags (the copyright tag can be included after author, before license). This should be at the top of each .php file, so that, when seen out of context, all of the relevant data about the project the file comes from is present.

For the main plugin file, it is then followed by the custom @wordpress-plugin tag which then starts the plugin header tags. WordPress is happy with this, as it is still within the first 8192 characters of the file, but also allows a plugin for phpDocumentor or other documentation generation application to parse out this plugin header data and display it in some way, and not just as one continuous long description which has line breaks removed, which is would do otherwise. The custom tag follows the format of being prefixed with a vendor ID.

tommcfarlin commented 11 years ago

I really like this because I'm a fan of doing DocBlocks that play nice with both tools such as phpDocumentor and the WordPress plugin header. I'm likely to begin doing this in my own work from now on, so thanks for showing me this.

For the Boilerplate, the problem is that this is something that is non-conventional to the average WordPress plugin developer (of course, we've established good practices transcend platforms or whatnot so don't misunderstand me :)).

So I'm all for promoting practices like this, but - as you've seen throughout the plugin - I'd need to add a TODO to document why this particular style of DocBlock has been added. This has me debating if it is worth the effort of including especially when I'm afraid it may raise more questions than providing true guardrails that developers could follow.

Interested in keeping this particular conversations going, so let me know your thoughts as it relates to the range of experience of WordPress plugin developers (obviously I'm a fan and, as I said, I'll be doing this myself in my own work).

tommcfarlin commented 11 years ago

Actually, I believe I've come up with a compromise that I'm happy with using:

I believe that this provides the necessary guardrails for WordPress developers basing their code off of this Boilerplate.

GaryJones commented 11 years ago

I don't think the TODO labels really help. Yes, they make it clear that something needs to be done, but it doesn't help newbies know what needs to be done. Consider changing them to actual example values (example.com, John Smith, 1970-01-01, My Foobar Plugin, etc.).

I don't think an explanation is necessarily needed for each design decision for the default code, but that could easily be something added to this projects readme or FAQ.txt, even if the answers pretty much direct them to this Issue.

GaryJones commented 11 years ago

The classical DocBlocks should be in each .php file - certainly the main plugin file and the class file, as well as uninstall.php. Arguably it should also be in the .php files for the views, but that's less important.

As you can see from my linked example, the documentation is still easy to read, and easily picked up by those not otherwise familiar with it. The examples of the Codex are really the minimum viable plugin with a couple of extras. This boilerplate is about doing everything as "properly" as possible.

tommcfarlin commented 11 years ago

The classical DocBlocks should be in each .php file - certainly the main plugin file and the class file, as well as uninstall.php. Arguably it should also be in the .php files for the views, but that's less important.

In the next push, you'll see that uninstall.php has a full DocBlock implemented. I'll also be including them in the views, as well.

As you can see from my linked example, the documentation is still easy to read, and easily picked up by those not otherwise familiar with it. The examples of the Codex are really the minimum viable plugin with a couple of extras. This boilerplate is about doing everything as "properly" as possible.

My main rub with this is that there's a disconnect between what beginner developers will see in the Codex and what they see in the Boilerplate. But, you know, I'm all for promoting good practices and if the need arises to justify what I've opted to including the DocBlocks in addition to the WordPress Plugin Headers, then I'll take the opportunity as a point of education.

Convinced :+1:

GaryJones commented 11 years ago

There's no harm in updating the codex with an "Advanced Example", that shows how to tie it all in with DocBlock documentation.

Also, is there a reason for removing the class-level documentation DocBlock?

tommcfarlin commented 11 years ago

It wasn't intentionally removed - it was left at the top of the file during some refactoring yesterday. :)

tommcfarlin commented 11 years ago

Resolved in this commit

GaryJones commented 11 years ago

That's still not right. Page-level and class-level DocBlocks are two separate things. In a file that has a class, you'll have one of each. See this as an example. Pick a random class in phpDocumentor itself for another example.

Page-level documentation should be at the top of the page, before any code.

GaryJones commented 11 years ago

As of this moment, there's obvious inconsistencies between page-level docblocks. @copyright is not added to each, and @since aren't needed for files and @link is sometimes gives as TODO instead of the URL using example.com.

See the following examples of how it should be: