Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Add support for long descriptions for tasks #16

Closed
gggeek opened this Issue Jan 11, 2012 · 11 comments

Comments

Projects
None yet
2 participants
Collaborator

gggeek commented Jan 11, 2012

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?

Owner

indeyets commented Jan 11, 2012

I like the idea, but not the exact approach.

It would be in Pake's spirit to have pake_longdesc() function defined without explicit "task" parameter (similar to pake_desc()).

It is a good idea to use docblocks. Why not take it further and conform to PHPDoc syntax? First line would be the short description, and everything else would be the long description (well, except the lines which start with @).

And, by the way, comments for developers shouldn't be docblocks at all. they should use the "normal" comment-syntax

Collaborator

gggeek commented Jan 11, 2012

"I like the idea, but not the exact approach."

I agree - that's why I did not send a pull request :-)
I coded it this way to avoid subclassing PakeTask or rewriting pake_desc - and I found no easy way other than passing the task as 1st param.

About short/long description: why not? It makes sense

About comments for developers: what about @todo ? ;-)

Owner

indeyets commented Jan 11, 2012

@todo is a marker which excludes line from description context, so, that is not a problem.

So, this task is divided in the next parts:

  1. simple docblock parser, which can get PHPDoc-style short and long descriptions
  2. fix, which would make pake_desc() calls optional (pake_task() should detect docblocks automatically, if pake_desc() wasn't called)
  3. implement pake_longdesc() function in a manner similar to the new pake_desc()
Collaborator

gggeek commented Jan 11, 2012

+1

Owner

indeyets commented Jan 11, 2012

ok. I'm on it :)

@indeyets indeyets was assigned Jan 11, 2012

Owner

indeyets commented Jan 12, 2012

@gggeek I think it's mostly done. some minor tweaks left. can you try it? does it work for you?

Owner

indeyets commented Mar 29, 2012

I consider it fixed

@indeyets indeyets closed this Mar 29, 2012

Collaborator

gggeek commented Apr 2, 2012

Better late than never ( ;-) ): I just updated to pake 1.6.3 both ezpublishbuilder and ezextensionbuilder.
The desc/longdesc thing seems mostly ok.

One nitpick:

This comment is taken as shortdesc (both lines):

/**
* Some comment.
* And some more...
*

While the following is not (only 1st line as part of shortdesc)

/**
 * Some comment.
 * And some more...
 *

(note: if github eats up spaces: the 2nd comment has a whitespace before the opening * on every comment line)

@indeyets indeyets reopened this Apr 2, 2012

Owner

indeyets commented Apr 2, 2012

@gggeek I added code-quotation to your comment — it helps to see the issue.

Is first case a valid phpdoc block, anyway?

@indeyets indeyets added a commit that referenced this issue Apr 2, 2012

@indeyets indeyets removed unused vars. refs #16 6a1f560

@indeyets indeyets added a commit that referenced this issue Apr 2, 2012

@indeyets indeyets tests for phpdoc-parser. refs #16 fa6740c
Owner

indeyets commented Apr 2, 2012

@gggeek see commit above. I added the test and can't reproduce the bug

Owner

indeyets commented Jul 4, 2012

found limitation: "pake help" doesn't take shortened names of tasks as paramaters

@indeyets indeyets closed this in 0fd9b51 Jul 17, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment