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:

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.4

Version 0.2.4 has one really important bugfix:

• Sometimes Coda does a bad job of providing the environment variables promised by the plugin API... As far as I can tell, this is a problem only in Snow Leopard, and only with the bundled PHP 5.3.0 build. This version includes a fix for Coda's bug. :)

Two (slightly lamer) bugfixes:

• Fixed display of static keyword on class member variables.
• Re-enabled docblocks for functions that don't use the 1TBS.

And two brand new features:

• Added docblock generation for interfaces.
• Enabled documentation for one line functions and abstract functions.

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
 
/**
 * alphabet interface.
 */
interface alphabet {
 
    /**
     * getA function.
     * 
     * @access public
     * @return void
     */
    public function getA();
 
    /**
     * getB function.
     * 
     * @access public
     * @return void
     */
    public function getB();
 
}
 
 
/**
 * Abstract Alpha class.
 * 
 * @abstract
 */
abstract class Alpha {
 
    /**
     * foo function.
     * 
     * @access public
     * @abstract
     * @static
     * @param mixed $bar
     * @param mixed $baz
     * @param mixed $qux
     * @return void
     */
    abstract static function foo($bar, $baz, $qux);
 
    /**
     * bar function.
     * 
     * @access private
     * @abstract
     * @return void
     */
    abstract private function bar();
}
 
/**
 * Beta class.
 * 
 * @extends Alpha
 * @implements alphabet
 */
class Beta extends Alpha implements alphabet {
 
    /**
     * a
     * 
     * (default value: true)
     * 
     * @var bool
     * @access public
     * @static
     */
    static var $a = true;
 
    /**
     * b
     * 
     * (default value: array())
     * 
     * @var array
     * @access protected
     */
    protected $b = array();
 
    /**
     * c
     * 
     * @var mixed
     * @access private
     */
    private $c;
 
    /**
     * foo function.
     * 
     * @access public
     * @static
     * @param mixed $bar
     * @param int $baz. (default: 1)
     * @param mixed $qux. (default: null)
     * @return void
     */
    static function foo($bar, $baz = 1, $qux = null) { }
 
    /**
     * bar function.
     * 
     * @access private
     * @return void
     */
    private function bar();
 
    /**
     * _baz function.
     * 
     * @access private
     * @final
     * @param string $qux. (default: 'quux')
     * @return void
     */
    final function _baz($qux = 'quux') { }
 
    /**
     * qux function.
     * 
     * @access protected
     * @return void
     */
    protected function qux() { }
 
    /**
     * getA function.
     * 
     * @access public
     * @return void
     */
    public function getA() { }
 
    /**
     * getB function.
     * 
     * @access public
     * @return void
     */
    public function getB() { }
 
}
 
?>