indeyets/pake — Issue #16: Add support for long descriptions for tasks
Author: gggeek
Created: 2012-01-11 16:20:45+00:00
State: open

So far I have come up with the following implementation:
- add a new function pake_londgdesc( $desc='' ) to allow adding a long description to every task
- if $desc == '', the 'long' description is taken from the php docblock attached to the php function executing the task
- if pake_longdesc() is not called for a task (or docblock is empty), its long description is equal to its short one
- added a "help" task that takes as 1st parameter the name of another task to see its long description, eg "pake help build"

(available at the pakefile at https://github.com/gggeek/ezextensionbuilder/blob/master/pakefile.php)

And here is the explanation:

Writing a pakefile for a project is a very nice thing, considering that it boils down to writing php functions (esp. compared to ant / makefiles), but it is imho severely hampered by the lack of documentation about what is going on.

Esp. with a long lifetime / many developers project, having top-notch quality of the assumptions of the tasks is essential.
After many years it can e.g. be hard to remember the filesystem layout or xml tokens expected by the pakefile, and while php is a very much readable language, having better documentation of the available tasks would be imho a big improvement.

A common solution is to document the pakefile using wikis or word documents, but we all know that code and documentation tend to fall out of sync very easily. Otoh docblocks are well known, widely used and generally updated. The only downside of using them is that a single docblock now has 2 different users: developers of the pakefile and users of the pakefile. This is however countered by the fact that the pakefile developer can provide a custom long_desc instead of relying on docblock.

Last but not least the syntax $command help $subcommand is very common everywhere, from pear to svn.

Comments?