Revision [1667]
This is an old revision of DescribeActions made by DarTar on 2004-10-05 15:06:14.
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
CategoryDevelopment