posted by justin hileman 6 months, 2 weeks ago

PHP Docblock generator plug-in for Coda

Panic's Coda is my current favorite editor. It's not perfect yet, but they just keep making it better. Coda 1.6 and later support a great plug-in architecture that allows users to tweak the editor's functionality to match their own needs and coding style.

Plug-ins have access to the text of the current document and can perform modifications on it as desired. For example, you could write a plug-in to insert the current date and time into your document, change the case of selected text, run code through a custom validator, or even wrap code with a special tag.

These plug-ins are pretty rad, let me tell you.

One of the things I missed most when I started using Coda was the ability to magically generate docblocks. You see, I'm absolutely horrid at writing documentation. With semi-automatic docblocks, writing documentation has a ton less friction so I find myself doing it more.

The new plug-in architecture lends itself well to things like that, so I decided to write a docblock generator. You can download my PHP docblock plug-in here:

It's a little rough around the edges, but it works. Give it a spin, let me know where you'd like to see improvements. And be sure to check out the rest of the awesome plug-ins available over at Panic.

Updates

PHP Docblock Generator 0.2.3

Version 0.2.3 fixes a couple of text selection and trigger quirks:

Fixed a bug where docblocks would be inserted mid-line if the cursor wasn't at the start (now they just aren't generated).
(Finally) fixed quirks triggering the plugin introduced by the Coda 1.6.1 plugin API changes.

PHP Docblock Generator 0.2.2

Version 0.2.2 fixes a few bugs in function and class declaration parsing:

Fixed a display bug in functions with a default array() value.
Fixed a bug that prevented documenting any function parameters which followed a default array() value.
Fixed a bug that prevented displaying @abstract, @final and @static in some docblocks.

PHP Docblock Generator 0.2.1

Version 0.2.1 adds more valid php file extensions:

PHP Docblock generator now works with php, phtml, php3, php4, php5, ph3, ph4, ph5, phps, module, inc and install extensions.
This one goes out to all you Drupal developers :)

PHP Docblock Generator 0.2

Version 0.2 has several needed improvements:

Bug fixes

Fixed a bug that prevented documenting functions like '&foo'.
Fixed a bug with functions declared 'public final' instead of 'final public'.
Fixed a bug that prevented documenting abstract and final classes.

Improvements

Improved flexibility of function declaration parsing regex.
Improved @access guessing for functions and member variables.
Improved member var docblock formatting and insertion point.

Features

Added member variable type guessing based on assigned values.
Added fuction/method param type guessing based on default values.

Example Docblocks

<?php
 
/**
 * Beta class.
 * 
 * @extends Alpha
 */
class Beta extends Alpha {
 
    /**
     * @var boolean $a
     * 
     * (default value: true)
     * 
     * @access public
     */
    static var $a = true;
 
    /**
     * @var array $b
     * 
     * (default value: array())
     * 
     * @access protected
     */
    protected $b = array();
 
    /**
     * @var mixed $c
     * @access private
     */
    private $c;
 
    /**
     * foo function.
     * 
     * @access public
     * @param mixed $bar
     * @param mixed $baz. (default: null)
     * @return void
     */
    function foo($bar, $baz = null) { }
 
    /**
     * bar function.
     * 
     * @access private
     * @return void
     */
    private function bar() { }
 
    /**
     * _baz function.
     * 
     * @access private
     * @return void
     */
    function _baz() { }
 
} ?>

comment

Comments

comment by Philip Morton 1 week, 3 days later

Very useful, thanks!

comment by Philipp 3 weeks, 4 days later

Very useful indeed, thank you very much. The plugin, however, lacks support for final functions and does not work when asked to comment such a function. Example:

public final function Bar(){}

Best wishes,
Philipp

comment by justin hileman 3 weeks, 6 days later

Thanks for pointing that out. It did support functions declared as final public, but not public final. I've improved the logic (in a couple more places, too), and it's far more flexible now.

See the rest of the improvements above, or download PHP Docblock Generator 0.2 and try it for yourself :)

Let me know if that works for you.

comment by Oliver 2 months, 2 weeks later

Hey there, I've been having some trouble.
Sometimes it acts funky. I can normally add a docblock anywhere, but sometimes, in certain classes/methods, it freezes coda and I have to force restart. It's basically un unsable for me because of this, although it is a great plugin.

comment by justin hileman 2 months, 2 weeks later

I've never run into that problem with this plugin. Can you help me track it down?

What other plugins do you have installed? Can you send me a file/class/method that you're having trouble with? Can you reliably recreate the problem, or does it seem random?

Thanks.

comment by Davy Van Den Bremt 2 months, 2 weeks later

Great plugin! Thanks!

But I had to sniff through the code to see that you're checking file extensions. I'm using Drupal and the extensions there are... (module, install). Could you add those by default? Would be great.

$valid_ext = array('php', 'phtml', 'php3', 'php4', 'php5', 'ph3', 'ph4', 'ph5', 'module', 'inc', 'install');

comment by justin hileman 2 months, 2 weeks later

Done. I even added phps for PHP source files.

It would be great if Coda told the plugin which syntax mode was currently active, but I haven't been able to figure that one out.

comment by Poser 3 months, 2 weeks later

I don't get how this is suppose to work, nothing seems to happen.

Can you give an example on how to use ?

comment by justin hileman 3 months, 2 weeks later

Sure.

Position the cursor in the white space at the start of the first line of a function, class variable, or class definition (or the empty line before) and hit control+shift+D. You can also select "Generate PHP Docblock" from the plugin menu.

It should automagically come up with a docblock for you and position your cursor where you need to start typing the description.

So type this:

class Foo extends Bar {

Then hit cmd+left to get to the start of the line (or up to get to the line above), then control+shift+D. It will add a comment that looks like this:

/**
 * Foo class.
 * 
 * @extends Bar
 */
class Foo extends Bar {

Aside: in previous versions of Coda you didn't have to position the cursor in the white space before or the above the line you want to document, but they changed the way the plugin API works slightly and that functionality broke

Post new comment

Twitter profile Last.fm profile Flickr profile FriendFeed profile Linked In profile