Lot 49: Greg Beaver's blog - phpDocumentor

PhpDocumentor 1.3.1 is released

nospam@example.com (Greg Beaver) — Tue, 24 Oct 2006 19:44:49 -0700

PhpDocumentor 1.3.1 has been released at both pear.php.net and sourceforge.net. This release addresses a problem with the sourceforge release, as well as a few other minor bugs. You can download it at http://pear.php.net/PhpDocumentor, or through sourceforge at http://sourceforge.net/project/showfiles.php?group_id=11194

PhpDocumentor 1.3.0 stable is released

nospam@example.com (Greg Beaver) — Fri, 18 Aug 2006 08:15:53 -0700

RELEASE ANNOUNCEMENT
PhpDocumentor 1.3.0 stable
August 18, 2006
Download:
pear upgrade PhpDocumentor
http://pear.php.net/PhpDocumentor
http://sourceforge.net/project/showfiles.php?group_id=11194&package_id=10450&release_id=440432
Information and documentation:
http://www.phpdoc.org

The PhpDocumentor team would like to announce the release of PhpDocumentor version 1.3.0. This is the first stable release since 2003, and marks a dramatic step up from previous releases.

This release adds in:

full PHP 5 support, including knowledge of internal classes for PHP version 5.1.0+ using the Reflection extension.
highlighting of tutorial XML
beautifying of output from the XML:DocBook/peardoc2:default converter

In addition, the release fixes more than 100 bugs found since version 1.2.3. Output from source highlighting is much more efficient, resulting in slightly smaller file size for option sourcecode=on. Multi-national characters are now allowed in a package name, although internationalization support is not fully complete.

PhpDocumentor is the standard automatic documentation solution for PHP written in PHP. Originally inspired by JavaDoc, PhpDocumentor has over 6 years of battle-testing and is bundled in popular IDEs such as Zend Studio, PHPEdit, PhpEd, and others.

On a personal note, I've been working hard on this release (minus a year-long hiatus) to get it working, and am very excited to finally see it out in the wild. Enjoy!

phpDocumentor and get/set/__call - give us your ideas (RFC)

nospam@example.com (Greg Beaver) — Thu, 13 Jul 2006 13:50:00 -0700

One of the trickier feature requests for phpDocumentor has been documenting "magic" object properties and methods. By "magic" I am referring to properties and methods that are created dynamically by PHP 5.0+ userspace class methods __get, __set, __isset, __unset and __call. For instance, this code creates a read-only property named $foo and a write-only property named $bar and a regular property named $regular as well as a magic function borp() that accepts two parameters.

<?php
class blah
{
private $_thingy;
private $_bar;

function __get($var)
{
switch ($var) {
case 'foo' :
return 45;
case 'regular' :
return $this->_thingy;
}
}

function __set($var, $val)
{
switch ($var) {
case 'bar' :
$this->_bar = $val;
break;
case 'regular' :
if (is_string($val)) {
$this->_thingy = $val;
}
}
}

function __call($method, $params)
{
if ($method == 'borp') {
if (count($params) == 2) {
return $params[0] * $params[1];
}
}
}
}
?>

In order to document this stuff, we want to add 4 new tags that would only be recognized in a class docblock. They are:

@property - magic class variables that can be both read and written to
@property-read - magic class variables that can only be read
@property-write - magic class variable that can only be written to
@method - magic class methods

@property and company would have this basic format:

@property type $varname [description]

@method would have this basic format:

@method returntype function_name(type $param1[ = ][, type $param2[ = ]...]) [description]

So, in order to document the previous example code, we would use:

<?php
/**
* show off @property, @property-read, @property-write, @method
*
* @property mixed $regular regular read/write property
* @property-read int $foo
* @property-write string $bar
* @method int borp(int $int1, int $int2) multiply two integers
*/
class blah
{
private $_thingy;
private $_bar;

function __get($var)
{
switch ($var) {
case 'foo' :
return 45;
case 'regular' :
return $this->_thingy;
}
}

function __set($var, $val)
{
switch ($var) {
case 'bar' :
$this->_bar = $val;
break;
case 'regular' :
if (is_string($val)) {
$this->_thingy = $val;
}
}
}

function __call($method, $params)
{
if ($method == 'borp') {
if (count($params) == 2) {
return $params[0] * $params[1];
}
}
}
}
?>

This example is rather poor usage of __get/__set/__call, but our point is the documentation, so ignore that for now . We will be accepting feedback for about two weeks, and at that point will announce the decision of how these things will be documented at http://www.phpdoc.org. If you are a developer of an IDE and would like to standardize this decision, or are a user with a real need for this feature, please let us know if there is a better way of doing that that we have not thought of. Comment on this entry or send an email to cellog at the-language-we're-talking-about.net

How can you help out with PEAR or phpDocumentor?

nospam@example.com (Greg Beaver) — Fri, 26 May 2006 09:50:28 -0700

We have had many inquiries from people who wish to assist with developing phpDocumentor or with PEAR. For those of you have written, thank you. However, most requests are along the lines of "how can I help?" and typically do not continue when we answer. Unfortunately, I've taken to a rather nihilistic view of these inquiries. Interestingly enough, most people who do end up helping out skip the question "how can I help?" altogether!

The question itself is not useful because there is plenty of evidence out there suggesting how to help out. Both PEAR and phpDocumentor have bug trackers [1]. These trackers list issues that have not been solved, and features that have not been implemented. If you want to help out a project, take a look at the bugs, choose one, and write a message along the lines of this (feel free to cut and paste):

"Hi,

my name is XXXX and I would like to fix Bug #1234 for the [fill in project name like PEAR or PhpDocumentor] project. If this issue has already been handled, I would instead like to take on Bug #1235. Do you have any objection?

Thanks,
Joe Shmoe"

Don't even wait to hear back from us, the next step is to fix the bug. Become good friends with the "cvs diff -u" command, and use that to email a patch back. The email should look something like:

"Hi,

I have a fix for Bug #1234, attached to this email as a unified diff against current CVS for [fill in project name like PEAR or PhpDocumentor]. If it looks good, could you commit the patch and close the bug?

Thanks,
Joe Shmoe"

If, in the course of attempting to fix the bug, you encounter a problem (such as not being able to access CVS), or don't understand something about the code, do not give up! Instead, send an email along these lines:

"Hi,

While attempting to fix Bug #1234, I have run up against some confusion. [...Describe what you don't understand, or what is not working the way you expect]. Can you help me figure this out?

Thanks,
Joe Shmoe"

Where, you might ask, should I send these emails? For both projects, there are public mailing lists devoted to the development of the projects. The best thing you can do is to send a message to these lists, and copy the lead developer (for PEAR/phpDocumentor, me) of the project in question. PEAR's list is pear-core@lists.php.net, and phpDocumentor's list is phpdoc-devel@lists.bluga.net. These are standard mailing lists, so the usual drill of sending a message to "phpdoc-devel-subscribe@lists.bluga.net" or "pear-core-subscribe@lists.php.net" will suffice to get you started. You can email me directly by taking the domain name of this blog and substituting an "at" symbol for the first period before the quartet part of the domain.

Until we have a history of working together, always assume that your code needs work, and set aside concerns of ego. It doesn't matter how much coding experience you have, what matters is diligence, humility and the ability to respond productively to criticism of the code itself (i.e. try to fix problems and then re-send the patch). In most cases, if a patch fixes a bug but is slightly flawed, I will simply commit it with modification to fix the slight flaw. If you're following the pear-cvs@lists.php.net list (or php.pear.cvs through news.php.net), you can see the way I have modified your patch, and learn for the next bug you fix or feature you implement. Above all, don't be intimidated, it's just PHP, and even if you do submit total crap code, it will be caught by either the developers or the unit tests (at least for PEAR).

As for helping out with phpDocumentor, it may be overwhelming to see the number of bugs in the list. What we really need from a developer is to develop a set of regression tests, so that as we clean the source code, we don't break anything. For instance, I plan to streamline all of the parsers, and to remove or revamp the internal caching mechanism inside conversion. This will be a huge project, even though the change is incremental, and will be the first step towards implementing the memory hogging.

PEAR 1.4.x is in a bugfix mode, but we are working on version 1.5.0. There are already tons of regression tests in place, so this is more a question of helping out with design and development of new features. Currently, there is one open bug report about a fatal error when installing through a third-party system (gentoo ebuild) that needs looking at and could be an easy first project for a new developer.

Frankly, if you wish to help out, you almost don't need to ask permission! Just email with a patch solving a bug or implementing a feature. What's the worst thing that could happen? You'd spend some time learning how these vastly important projects actually work, and maybe even improve your own PHP expertise in the process. Even if your code is not accepted (bug fixes are almost always accepted as submitted, feature requests may not be), you come out ahead, and in the best case, you can get credit for fixing an issue that affects thousands and thousands of users. Not too bad, eh?

[1]

PEAR bug tracker

phpDocumentor bug tracker at PEAR

phpDocumentor bug tracker at sourceforge.net

phpDocumentor: taking advantage of source code highlighting in custom templates

nospam@example.com (Greg Beaver) — Mon, 22 May 2006 03:47:56 -0700

Recently, phpDocumentor 1.3.0RC6 was released (1.3.0 stable is coming soon, stay tuned). In this release, I finally got around to fixing the problem with source highlighting and CSS in the HTML templates. If you have been using your own custom template based on the standard distributed templates, you will need to make a few changes. Most importantly, you'll need to go into your options.ini and make changes similar to this:

http://cvs.php.net/viewcvs.cgi/pear/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/options.ini?r1=1.2&r2=1.3

In addition, you'll want to make sure your style sheet has an entry similar to this:

http://cvs.php.net/viewcvs.cgi/pear/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/templates/media/stylesheet.css?r1=1.1&r2=1.2

If you based your template off of another of the templates, you can see the exact choices you need by examining CVS of phpDocumentor (the above links can be used to navigate to the template you need)

Happy documenting!

phpDocumentor and PEAR - interesting crossing of paths

nospam@example.com (Greg Beaver) — Tue, 02 May 2006 14:31:00 -0700

Yesterday and today I released phpDocumentor 1.3.0RC6. Aside from a number of exciting features and many important bug fixes, including some bugs opened over 2 years ago (!) this release is unique in another way: in addition to working as a PEAR-installable package, it also works as an extracted file.

This is a subtle but revolutionary change. In order to do this, we have to take advantage of some interesting possibilities that package.xml 2.0 provides. In fact, I designed several of the features of package.xml 2.0 to support this duality. In particular, it is possible to bundle a file and completely ignore it. We use this feature to handle the duality of the "phpdoc" command itself.

When installed through PEAR, a file named "pear-phpdoc" is installed as "phpdoc", and if installed on windows, "pear-phpdoc.bat" is installed as "phpdoc.bat." Also bundled in the archive are the original "phpdoc" and "phpdoc.bat" commands needed to run phpDocumentor out of the box just by extracting the archive. These files are simply ignored by the PEAR installer.

Another feature unique to package.xml 2.0 that makes this possible is the usage of package-time file tasks. In particular, the replace task, which is used to set the version of phpDocumentor as displayed by the actual generation and the docbuilder web interface.

In addition, I finally updated the manual at http://www.phpdoc.org/manual to the current version.

So in short, things are coming together finally.

finally - a new release of phpDocumentor

nospam@example.com (Greg Beaver) — Tue, 29 Nov 2005 00:26:10 -0800

phpDocumentor has been foundering for about a year, while I struggled with the PEAR installer. Well, just now I released 1.3.0RC4 through pear.php.net. A sourceforge release will follow some time in the next week or so. This release is significant in that it fixes fatal errors encountered in PHP 5.0.5, and several significant bugs. There is more work to be done before 1.3.0, but this is a big relief for me.

Getting this one out the door proved to be very difficult. pear.php.net was timing out prior to finishing the release upload process. This always sucks. I did a bit of debugging (thank you ZDE 5.0) and some serious refactoring to the pearweb code. What really surprised me was an incredible inefficiency in Archive_Tar that was actually iterating over the entire archive even when requested files had been extracted. I fixed this manually up at pear.php.net, and even with the existing inefficient pearweb code, the upload completed successfully. Wheeee, isn't development fun

new PECL docblock extension is a significant step forward in docblock parsing

nospam@example.com (Greg Beaver) — Mon, 21 Nov 2005 23:03:47 -0800

I just released pecl at pecl.php.net, my first PHP extension. docblock is to phpDocumentor docblocks what the tokenizer extension is to PHP itself. It takes a docblock as an argument, and returns an array of tokens. Parsing docblocks in PHP has always been a major pain, and also very difficult to do correctly, because certain kinds of code simply won't parse correctly without a proper scanner (such as docblocks containing <code> and @fopen - phpDocumentor 1.3.x will try to parse the "@fopen" tag).

The docblock extension is tested only with PHP 5.1.0, but I'm sure it can be adjusted to work with all PHP versions, as the interface with PHP logic is ridiculously simple. Once I have a chance to test it with other PHP versions, it will be available for them as well. To make the scanner, I used re2c at the suggestion of people on the EFNet pecl IRC channel, and this was wonderful. I had been

The extension is fully regression tested, and as such should work in every case. To install, simply use "pecl install docblock" on unix. A windows .dll is not yet available, but probably will be soon on pecl4win.

As you might have guessed, phpDocumentor is alive and well. The single largest problem with version 1.3.x and earlier is that it scales terribly. In addition, the use of Smarty templates is rather unflexible and difficult to maintain properly. Because of these shortcomings, after version 1.3.0 is released, it will be feature-frozen, and only bugs will be fixed. All new features are being developed in a PHP 5.1+ version of phpDocumentor that will have the ability to store data. This means incrementally parsing a large project will be possible, and in fact, the ability to only parse changed files is possible as well. In addition, the use of a few essential PHP extensions like docblock and reflection will be used to better manage the parsing. Reflection will be used for built-in classes like Exception.

However, first, we need to get phpDocumentor 1.3.0 out the door, and to that effect, look for 1.3.0RC4 very shortly. This release will fix critical PHP5-related problems, and a few other issues. There are many small edge case bugs that are more annoyances than functional problems which will be addressed in future releases. Stay tuned!

latest addition: docblock lexer/parser combo

nospam@example.com (Greg Beaver) — Fri, 01 Jul 2005 19:13:52 -0700

my initial foray into the bug list at sourceforge for phpDocumentor has led to an unshakable conclusion: the docblock "parsing" currently used in phpDocumentor, well, sucks.

So, to solve problems such as this code breaking:

/**
* Watch the @include_once become a tag...
*
* Example:
* <code>
* @include_once 'oops_stupid_docblock_Parser.php';
* </code>
*/

I have started a hand-written lexer with an eye towards a phpJay-generated docblock parser. I had originally attempted a phpLex auto-generated lexer for docblocks, but it quickly became a 2000-line plus undebuggable mess of spaghetti. In addition, it simply couldn't do some things it needs to do, and so the docblock parser was far more complex than is healthy. With the current code in cvs (700-something lines), the lexer supports everything the current one does plus proper handling of things like {@internal}} and special tags <code></code>. More interesting, it supports nested simple lists (something humans intuitively can read) and has unit tests. There's work to be done (edge cases, and I just realized I forgot to implement <ul><ol><li>) but mostly we're fast on the way to an improved docblock parsing system, the first in a series of minor refactors that will add up to a major improvement in code, performance, and memory usage of phpDocumentor.

development restarts after a year

nospam@example.com (Greg Beaver) — Sun, 12 Jun 2005 11:10:57 -0700

Bongiorno! I am writing this entry from Reggio Emilia, Italia where the weather is unbelievable and the generosity overflows.

That, however, is not the point of this entry. After a full year's vacation from phpDocumentor development, I finally took up the mantle again and have started fixing bugs in 1.3.0RC3 in preparation for RC4. In order to do this, I exported the bug list from sourceforge in xml format, and wrote a simplexml-based browser in about 1 hour. Development actually began in the terminal at Paris's Charles de Gaulle airport, and is moving quite briskly. 5 bugs down so far, averaging about 1 bug every 10 minutes of development time. Hopefully, by the time I return from Europe all of them will have been fixed

Lot 49: Greg Beaver's blog - phpDocumentor

PhpDocumentor 1.3.1 is released

PhpDocumentor 1.3.0 stable is released

phpDocumentor and __get/__set/__call - give us your ideas (RFC)

How can you help out with PEAR or phpDocumentor?

phpDocumentor: taking advantage of source code highlighting in custom templates

phpDocumentor and PEAR - interesting crossing of paths

finally - a new release of phpDocumentor

new PECL docblock extension is a significant step forward in docblock parsing

latest addition: docblock lexer/parser combo

development restarts after a year

phpDocumentor and get/set/__call - give us your ideas (RFC)