Revision [1715]
This is an old revision of DescribeActions made by JavaWoman on 2004-10-06 22:18:20.
Action Descriptor
One of the next steps for providing a comprehensive HelpInfo documentation is to add some clear information on all the actions shipped with the Wikka package (how to use them, what parameters they accept etc.).
I've written a simple "metaction" that retrieves automatically the list of actions stored in the actions/ folder and displays their description. This might save a lot of future work to keep infos updated since the action generates on-the-fly all the existing descriptions.
Here's the two-step implementation:
1. Add descriptions to action files
The idea came from JavaWoman's use of phpDocumentor headers in her code.
To make action infos retrievable we just need to add a basic header like the following in every action:
<?php
/*
* Title:
* COFFEE
*
* Source:
* actions/coffee.php
*
* Description:
* This action prepares a cup of great coffee every morning at 7:00 am
*
* Usage:
* {{coffee sugar="value"}}
*
* Parameters:
* sugar (int): specifies the number of spoonfuls of sugar. No value produces black coffee without sugar
*/
// action code follows
echo blablabla;
echo blablabla;
echo blablabla;
echo blablabla;
echo blablabla;
?>
/*
* Title:
* COFFEE
*
* Source:
* actions/coffee.php
*
* Description:
* This action prepares a cup of great coffee every morning at 7:00 am
*
* Usage:
* {{coffee sugar="value"}}
*
* Parameters:
* sugar (int): specifies the number of spoonfuls of sugar. No value produces black coffee without sugar
*/
// action code follows
echo blablabla;
echo blablabla;
echo blablabla;
echo blablabla;
echo blablabla;
?>
We might consider allowing some basic phpDocumentor tags.
2. Create a parser to retrieve and print descriptions
The following action get the files stored in the actions/ folder, extracts action descriptions and prints them. I've set the character limit to 600, but this can be changed.
Save the following code as actions/actionlist.php and use it as {{actionlist}}
<?php
/*
* Title:
* ACTION LIST
*
* Source:
* actions/actionlist.php
*
* Description:
* Displays a list of available actions with their description
*
* Usage:
* {{actionlist}}
*
* Parameters:
* none
*/
echo $this->Format("=== List of available actions === --- ");
$handle = opendir('actions/');
while (false !== ($file = readdir($handle))) {
if ($file != "." && $file != "..") {
echo $this->Format("**".substr($file, 0, -4)."** --- ");
$fd = fopen("actions/".$file, "r");
$contents = fread ($fd, "600");
if (ereg( "(/\*)(.+)(\*/)", $contents, $desc)) {
$desc[0] = preg_replace("((/\*)|(\*/)|(\n\*))", "\n", $desc[0]);
echo $this->Format("@@".$contents."@@ --- ");
// Please replace in the previous line @@ with two % signs.
// Couldn't do it in a wikka highlighted code block!
}
fclose($file);
}
}
closedir($handle);
?>
/*
* Title:
* ACTION LIST
*
* Source:
* actions/actionlist.php
*
* Description:
* Displays a list of available actions with their description
*
* Usage:
* {{actionlist}}
*
* Parameters:
* none
*/
echo $this->Format("=== List of available actions === --- ");
$handle = opendir('actions/');
while (false !== ($file = readdir($handle))) {
if ($file != "." && $file != "..") {
echo $this->Format("**".substr($file, 0, -4)."** --- ");
$fd = fopen("actions/".$file, "r");
$contents = fread ($fd, "600");
if (ereg( "(/\*)(.+)(\*/)", $contents, $desc)) {
$desc[0] = preg_replace("((/\*)|(\*/)|(\n\*))", "\n", $desc[0]);
echo $this->Format("@@".$contents."@@ --- ");
// Please replace in the previous line @@ with two % signs.
// Couldn't do it in a wikka highlighted code block!
}
fclose($file);
}
}
closedir($handle);
?>
The output will look like the following:
actionlist
Title:
ACTION LIST
Source:
actions/actionlist.php
Description:
Displays a list of available actions with their description
Usage:
{{actionlist}}
Parameters:
none
(...)
coffee
Title:
COFFEE
Source:
actions/coffee.php
Description:
This action prepares a cup of great coffee every morning at 7:00 am
Usage:
{{coffee sugar="value"}}
Parameters:
sugar (int): specifies the number of spoonfuls of sugar. No value produces black coffee without sugar
color
Title: COLOR ...
(...)
-- DarTar
DarTar, thanks for stealing my idea! :)
When releasing my WikkaEmailToolkit code, I wanted to make sure it was "properly" documented. I was aware of the existence of "phpDoc", had come across examples, and they looked familiar. Guess why? Consider my alias here, JavaWoman. Although I don't do Java anymore, I did once. I also did quite a bit of Smalltalk, later, in a previous life. And occasionally I did, and do, Perl. Anyway, I know phpDoc (and the phpDocumentor implementation) was based on JavaDoc. Which itself was based on .... well, a few days ago I was discussing the idea of documenting PHP code with a colleague over IM, both of us Googling while we talked. Both of us coming up with JavaDoc (of course). And then he mentioned AutoDoc ... ah, yes, now where did I come across that before? Google a bit and you'll see.
Anyway, this way of making "self-documenting code" is really very old already; its basic syntax is familiar to many programmers, and many tools exist that can make (some) sense of it.
So yes, I also thought that actions should be documented in a similar way. But not in a different way!
My reaction is simply: thanks for coming up with the idea - think about it and it's self-evident - but why reinvent the wheel?The wheel has been invented already and it's quite efficient and mature.
You say: "We might consider allowing some basic phpDocumentor tags."
I'd say: Just write standard phpDocumentor code, and use some of its basic tags for a limited version.
That has two advantages:
- The idea and even the syntax is already familiar to many programmers
- The documentation blocks can be used by both a "local" Wikka "documentor" and phpDocumentor (which could put things in a larger context than merely a list of action descriptions).
- It might actually interfere with phpDocumentor.
The difference between your docblocks and the phpDoc syntax is subtle, and might easily be overlooked. In actual phpDoc syntax a block starts with /** (note there are two stars), then has a number of lines each starting with a single star, and is ended by */. Such a block would be handled by your little parser - but merely reproduce the phpDoc descriptions and tags. On the other hand, just adding that single star to the first line of the block (no problem for your proposed parser) would cause it to be parsed by phpDoc as well - but producing nothing but "description", not structured documentation.
Instead, I would propose a "little parser" that makes use of a basic subset of phpDoc tags (while igonring others!), so that a local documentation set could be produced quickly, while the same documentation block for phpDoc (with optionally a longer description and more tags) would produce structured and cross-referenced documentation when run through phpDocumentor.
I haven't tried this yet (though I intended to do that already)... But as I understand it, a separate file for phpDocumentor is a "package"; while an action in Wikka is sort of a "procedure": something you tell to "do" something, possibly with a set of parameters. (A "procedure" is a somewhat different concept than a "function"; some programming languages treat them as the same thing, but not all do - PHP doesn't but I grew up with languages that did.) So for phpDocumentor to process documentation for an action, you'd have at least a @package tag which names the thing; you'd also have a short description; and you'd have a number of @param tags (where you specify type, name, required/optional and purpose of each). I think that would work - and it would essentially cover all you propose. You can (with phpDocumentor) even "invent" your own tags, so you could add, say, a @usage tag.
I'd want a little time to play with this (using phpDocumentor for actions)... but essentially my reaction is:
Great idea - but don't reinvent the wheel: reuse it!
-- JavaWoman
Challenge taken up - and actually these few lines of code were just meant to be an example, not a real proposal for yet-another-documentation-syntax. I personally welcome the possibility of phpdoc compliant headers in wikka, but keep in mind that one of the priorities of this wiki engine is its lightness. I'm not sure Jason would be happy to see a phpdoc class larger than the rest of the wiki engine ;p If there is a way to adapt a subset of phpdoc scripts as a light wikka action, why not give it a try...
Jason, your opinion?
-- DarTar
I think you could easily parse out just a small subset of phpDoc tags (plus the short description which should be at the start anyway) and maintain the Wikka "lightness" that, without necessarily forbidding other phpDoc documentation or hindering phpDocumentor from coming up with its highly useful cross-referenced documentation. (But I think you should forget about re-using phpDocumentor code, it's doing a *lot* that you don't want anyway.)
Comments by themselves do add (marginally) to execution speed (PHP has to read in the code) but there are solutions for that - while the fact that the Wikka code is already well-documented was one of the reasons for me to try this over other Wiki flavors. Open source without any documentation is just a guessing game.
I'll try to make a docblock tomorrow (oops.. later today!) for one action file I'm working on anyway, and see what would be needed at minimum for both parsers to come up with useful docs from that (and in combination with what phpDocumentor does now with my version of wikka.php). More later...
-- JavaWoman
CategoryDevelopment
