Revision [1664]

This is an old revision of DescribeActions made by DarTar on 2004-10-05 14:34:54.

 

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 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 action
*
* 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
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:


(...)

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
There are 2 comments on this page. [Show comments]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki