[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