Home > Web Development > Why You Can’t Live Without PHPDoc in PHPEd

Why You Can’t Live Without PHPDoc in PHPEd

March 2nd, 2009

I am a responsible driver. As such, I follow the posted speed limit… most of the time. I am also a responsible PHP coder. As such, I document my code. I’ll admit, sometimes my documentation is nearly worthless. I’m sure some of you will recognize documentation examples like this one:

//An array of employees.
protected $EmployeeArray;

I’ll also admit that, although I’ve seen plenty of documentation and real-world examples of PHPDoc in use, I’ve never used that documentation format myself. That is, until now. Recently, I discovered that PHPEd uses PHPDoc comments to assist with intelligent code completion. That’s just the kind of pragmatic kick-in-the-butt I needed to start documenting my code in a well-established format.

What is PHPDoc?

PHPDoc is a formal documention format for PHP code. If you use it, you can use tools like PHPDocumentor to build formatted manual-style documentation for your code. What I found most useful was that it also allows IDEs like PHPEd to provide explicit code completion for otherwise mixed value variables and objects. I recommend reading more about PHPDoc on Wikipedia: http://en.wikipedia.org/wiki/PHPDoc.

How do I use PHPDoc in PHPEd?

Well, let’s start with a simple example. Consider the following uncommented code:

class Employee {
    public $Name;
    public $Title;

    public function __construct($Name, $Title) {
        $this->Name = $Name;
        $this->Title = $Title;
    }
}

class Department {
    public $Name;
    public $Employees;

    public function __construct($Name) {
        $this->Name = $Name;
        $this->Employees = array();
    }

    public function AddEmployee($e) {
        $this->Employees[] = $e;
    }
}

We can start adding PHPDoc comments to this code easily. In fact, PHPEd makes it so simple, I now consider it a crime not to do so.

All PHPDoc comments start with /**. So, type /** directly above the constructor method definition for the Employee class and press Enter. See what happens? It’s magical! PHPEd gives you a nearly complete PHPDoc block for free. All you need to do is flesh it out. So far, we have this:

class Employee {
    public $Name;
    public $Title;

    /**
    * put your comment there...
    *
    * @param mixed $Name
    * @param mixed $Title
    * @return Employee
    */
    public function __construct($Name, $Title) {
        $this->Name = $Name;
        $this->Title = $Title;
    }
}

class Department {
    public $Name;
    public $Employees;

    public function __construct($Name) {
        $this->Name = $Name;
        $this->Employees = array();
    }

    public function AddEmployee($e) {
        $this->Employees[] = $e;
    }
}

Pretty cool, huh? Next, do the same thing for both of the member variables of the Employee class:

class Employee {
    /**
    * put your comment there...
    *
    * @var mixed
    */
    public $Name;

    /**
    * put your comment there...
    *
    * @var mixed
    */
    public $Title;

    /**
    * put your comment there...
    *
    * @param mixed $Name
    * @param mixed $Title
    * @return Employee
    */
    public function __construct($Name, $Title) {
        $this->Name = $Name;
        $this->Title = $Title;
    }
}

class Department {
    public $Name;
    public $Employees;

    public function __construct($Name) {
        $this->Name = $Name;
        $this->Employees = array();
    }

    public function AddEmployee($e) {
        $this->Employees[] = $e;
    }
}

We’re going to do the same thing for the member variables and methods of the Department class. This time, I’ll fill in all appropriate comment information.

class Employee {
    /**
    * The Employee's name.  This should be the employee's full name,
    * like Bob Johnson.
    *
    * @var mixed
    */
    public $Name;

    /**
    * The Employee's title.  This should be the complete, unabbreviated
    * title, like Chief Operations Officer.
    *
    * @var mixed
    */
    public $Title;

    /**
    * Creates a new Employee with the supplied Name and Title.
    *
    * @param mixed $Name
    * @param mixed $Title
    * @return Employee
    */
    public function __construct($Name, $Title) {
        $this->Name = $Name;
        $this->Title = $Title;
    }
}

class Department {
    /**
    * The Department's name.
    *
    * @var mixed
    */
    public $Name;

    /**
    * An array of Employee objects.
    *
    * @var Employee
    */
    public $Employees;

    /**
    * Creates a new Department with the supplied name, and initializes the array of Employees.
    *
    * @param mixed $Name
    * @return Department
    */
    public function __construct($Name) {
        $this->Name = $Name;
        $this->Employees = array();
    }

    /**
    * Adds an employee to the Employees array.
    *
    * @param Employee $e
    */
    public function AddEmployee($e) {
        $this->Employees[] = $e;
    }
}

Take a look at the following block of code:

/**
* Adds an employee to the Employees array.
*
* @param Employee $e
*/
public function AddEmployee($e) {
    $this->Employees[] = $e;
}

This tells PHPEd’s code completion engine that we are expecting $e to be an Employee object. Why is this important? Well, now, PHPEd can do code completion on $e within the AddEmployee method. Take a look at this screenshot to see what I mean:

PHPDoc Code Completion

I’m sure you can see the benefits of this for a large project.

For more information, take a look at the following sites:

Nate Smith Web Development , , ,

  1. | #1

    Thanks for the motivation!
    After many years with PHPEd I never touched this.
    I’ll start using it right-away. :)

  1. No trackbacks yet.