[geeklog-cvs] geeklog: Updated function descriptions and phpDocumentor tags
geeklog-cvs at lists.geeklog.net
geeklog-cvs at lists.geeklog.net
Sun May 24 07:34:50 EDT 2009
details: http://project.geeklog.net/cgi-bin/hgweb.cgi/rev/05a9b14e24d4
changeset: 7050:05a9b14e24d4
user: Dirk Haun <dirk at haun-online.de>
date: Sun May 24 13:33:58 2009 +0200
description:
Updated function descriptions and phpDocumentor tags
diffstat:
system/lib-plugins.php | 316 ++++++++++++++++++++++++--------------------
system/lib-syndication.php | 9 +-
2 files changed, 175 insertions(+), 150 deletions(-)
diffs (truncated from 853 to 300 lines):
diff -r 484127470385 -r 05a9b14e24d4 system/lib-plugins.php
--- a/system/lib-plugins.php Sat May 23 08:52:57 2009 +0200
+++ b/system/lib-plugins.php Sun May 24 13:33:58 2009 +0200
@@ -35,6 +35,7 @@
* This is the plugin library for Geeklog. This is the API that plugins can
* implement to get tight integration with Geeklog.
* See each function for more details.
+* @link http://wiki.geeklog.net/index.php/Plugin_API
*
*/
@@ -76,6 +77,7 @@
*
* @param string $function_name holds name of function to call
* @return void
+* @access private
* @internal not to be used by plugins
* @todo only supports functions without any parameters
*
@@ -107,14 +109,15 @@
* @param string $function holds name of function to call
* @param array $args arguments to send to function
* @return mixed returns result of function call, otherwise false
+* @access private
* @internal not to be used by plugins
*
*/
function PLG_callFunctionForOnePlugin($function, $args='')
{
if (function_exists($function)) {
- if (empty ($args)) {
- $args = array ();
+ if (empty($args)) {
+ $args = array();
}
// great, function exists, run it
@@ -202,7 +205,7 @@
/**
* Calls the plugin function to return the current version of code.
-* Used to indicate to admin if an update or upgrade is requied.
+* Used to indicate to admin if an update or upgrade is required.
*
* @param string $type Plugin name
* @return boolean Returns true on success otherwise false
@@ -221,11 +224,11 @@
* @link http://wiki.geeklog.net/index.php/Plugin_Auto-Uninstall
*
*/
-function PLG_uninstall ($type)
+function PLG_uninstall($type)
{
global $_PLUGINS, $_TABLES;
- if (empty ($type)) {
+ if (empty($type)) {
return false;
}
@@ -234,7 +237,7 @@
$function = 'plugin_autouninstall_' . $type;
$remvars = $function();
- if (empty ($remvars) || $remvars == false) {
+ if (empty($remvars) || $remvars == false) {
return false;
}
@@ -256,7 +259,7 @@
for ($i = 0; $i < count($remvars['groups']); $i++) {
$grp_id = DB_getItem ($_TABLES['groups'], 'grp_id',
"grp_name = '{$remvars['groups'][$i]}'");
- if (!empty ($grp_id)) {
+ if (!empty($grp_id)) {
COM_errorLog ("Attempting to remove the {$remvars['groups'][$i]} group", 1);
DB_delete($_TABLES['groups'], 'grp_id', $grp_id);
COM_errorLog ('...success', 1);
@@ -270,7 +273,7 @@
for ($i = 0; $i < count($remvars['features']); $i++) {
$access_id = DB_getItem ($_TABLES['features'], 'ft_id',
"ft_name = '{$remvars['features'][$i]}'");
- if (!empty ($access_id)) {
+ if (!empty($access_id)) {
COM_errorLog ("Attempting to remove {$remvars['features'][$i]} rights from all groups" ,1);
DB_delete($_TABLES['access'], 'acc_ft_id', $access_id);
COM_errorLog ('...success', 1);
@@ -356,7 +359,7 @@
* @see PLG_pluginStateChange
*
*/
-function PLG_enableStateChange ($type, $enable)
+function PLG_enableStateChange($type, $enable)
{
global $_CONF, $_TABLES, $_DB_table_prefix;
@@ -405,7 +408,7 @@
$function = 'plugin_getmenuitems_' . $pi_name;
if (function_exists($function)) {
$menuitems = $function();
- if (is_array ($menuitems)) {
+ if (is_array($menuitems)) {
$menu = array_merge ($menu, $menuitems);
}
}
@@ -504,7 +507,7 @@
}
/**
-* Allows plugins a chance to handle a comment before GL does.
+* Allows plugins a chance to handle a comment before Geeklog does.
* This is a first-come-first-serve affair so if a plugin returns an error, other
* plugins wishing to handle comment preprocessing won't get called
@@ -512,12 +515,14 @@
* @author Tony Bibbs, tony AT tonybibbs DOT com
* @access public
* @param int $uid User ID
-* @param string $title Comment title
+* @param string &$title Comment title
+* @param string &$comment Comment text
* @param string $sid Story ID (not always a story, remember!)
* @param int $pid Parent comment ID
* @param string $type Type of comment
-* @param string $postmode HTML or text
+* @param string &$postmode HTML or text
* @return mixed an error otherwise false if no errors were encountered
+* @see PLG_itemPreSave
*
*/
function PLG_commentPreSave($uid, &$title, &$comment, $sid, $pid, $type, &$postmode)
@@ -548,7 +553,7 @@
}
/**
-* Allows plugins a chance to handle an item before GL does. Modeled
+* Allows plugins a chance to handle an item before Geeklog does. Modeled
* after the PLG_commentPreSave() function.
*
* This is a first-come-first-serve affair so if a plugin returns an error, other
@@ -559,6 +564,7 @@
* @param string $type Type of item, i.e.; registration, contact ...
* @param string $content item specific content
* @return string empty is no error, error message if error was encountered
+* @see PLG_commentPreSave
*
*/
function PLG_itemPreSave($type, $content)
@@ -569,7 +575,7 @@
$function = 'plugin_itemPreSave_' . $pi_name;
if (function_exists ($function)) {
$msgError = $function ($type, $content);
- if (!empty ($msgError)) {
+ if (!empty($msgError)) {
// Plugin doesn't want to save the item
return $msgError;
}
@@ -579,7 +585,7 @@
$function = 'CUSTOM_itemPreSave';
if (function_exists ($function)) {
$msgError = $function ($type, $content);
- if (!empty ($msgError)) {
+ if (!empty($msgError)) {
// Custom doesn't want to save the item
return $msgError;
}
@@ -599,9 +605,9 @@
* bear with us ...
*
* The only parameter to this function, $showsitestats, was documented as being
-* 1 for the site stats and 0 for the plugin-specific stats. However, the latter
-* was always called with a value of 2, so plugins only did a check for 1 and
-* "else", which makes extensions somewhat tricky.
+* being 1 for the site stats and 0 for the plugin-specific stats. However, the
+* latter was always called with a value of 2, so plugins only did a check for 1
+* and "else", which makes extensions somewhat tricky.
* Furthermore, due to the original templates for the site stats, it has
* become standard practice to hard-code a <table> in the plugins as the return
* value for $showsitestats == 1. This table, however, didn't align properly
@@ -621,12 +627,12 @@
* @return mixed array (for mode 3) or string
*
*/
-function PLG_getPluginStats ($showsitestats)
+function PLG_getPluginStats($showsitestats)
{
global $_PLUGINS;
if ($showsitestats == 3) {
- $retval = array ();
+ $retval = array();
} else {
$retval = '';
}
@@ -636,7 +642,7 @@
$function = 'plugin_statssummary_' . $pi_name;
if (function_exists ($function)) {
$summary = $function ();
- if (is_array ($summary)) {
+ if (is_array($summary)) {
$retval[$pi_name] = $summary;
}
}
@@ -660,7 +666,7 @@
$function = 'CUSTOM_statssummary';
if (function_exists ($function)) {
$summary = $function ();
- if (is_array ($summary)) {
+ if (is_array($summary)) {
$retval['Custom'] = $summary;
}
}
@@ -701,7 +707,7 @@
$function = 'plugin_searchtypes_' . $pi_name;
if (function_exists ($function)) {
$cur_types = $function ();
- if (is_array ($cur_types) && (count ($cur_types) > 0)) {
+ if (is_array($cur_types) && (count($cur_types) > 0)) {
$types = array_merge ($types, $cur_types);
}
} // no else because this is not a required API function
@@ -710,7 +716,7 @@
$function = 'CUSTOM_searchtypes';
if (function_exists ($function)) {
$cur_types = $function ();
- if (is_array ($cur_types) && (count ($cur_types) > 0)) {
+ if (is_array($cur_types) && (count($cur_types) > 0)) {
$types = array_merge ($types, $cur_types);
}
}
@@ -723,12 +729,13 @@
* Determines if a specific plugin supports Geeklog's
* expanded search results feature
*
-* @author Tony Bibbs, tony AT tonybibbs DOT com
-* @access public
-* @param string $type Plugin name
-* @return boolean True if it is supported, otherwise false
+* NOTE: This function is not currently used
*
-* NOTE: This function is not currently used
+* @author Tony Bibbs, tony AT tonybibbs DOT com
+* @access public
+* @param string $type Plugin name
+* @return boolean True if it is supported, otherwise false
+* @deprecated no longer used
*
*/
function PLG_supportsExpandedSearch($type)
@@ -747,7 +754,7 @@
/**
* This function gives each plugin the opportunity to do their search
-* and return their results. Results comeback in an array of HTML
+* and return their results. Results come back in an array of HTML
* formatted table rows that can be quickly printed by search.php
*
* @param string $query What the user searched for
@@ -765,10 +772,11 @@
function PLG_doSearch($query, $datestart, $dateend, $topic, $type, $author, $keyType = 'all', $page = 1, $perpage = 10)
{
global $_PLUGINS;
- /*
- The API, as of 1.6.0, does not use $page, $perpage
- $type is now only used in the core and should not be passed to the plugin
- */
+
+ /**
+ * The API, as of 1.6.0, does not use $page, $perpage
+ * $type is now only used in the core and should not be passed to the plugin
+ */
$search_results = array();
@@ -840,13 +848,15 @@
* The plugin is responsible for its own security.
* This supports a plugin having either a single menuitem or multiple menuitems.
* The plugin has to provide an array for the menuitem of the format:
-* array (menuitem_title, item_url, submission_count)
+* <code>
+* array(menuitem_title, item_url, submission_count)
+* </code>
* or an array of arrays in case there are several entries:
* <code>
-* array (
-* array (menuitem1_title, item1_url, submission1_count),
-* array (menuitem2_title, item2_url, submission2_count),
-* array (menuitem3_title, item3_url, submission3_count))
+* array(
+* array(menuitem1_title, item1_url, submission1_count),
+* array(menuitem2_title, item2_url, submission2_count),
+* array(menuitem3_title, item3_url, submission3_count))
* </code>
* Plugin function can return a single record array or multiple records
*
@@ -860,6 +870,7 @@
* @param string $function_name A string that gives the name of the function
* at the plugin that will return the values.
* @return array Returns options to add to the given menu that is calling this
+* @access private
More information about the geeklog-cvs
mailing list