[geeklog-cvs] geeklog: Documentation updates
geeklog-cvs at lists.geeklog.net
geeklog-cvs at lists.geeklog.net
Sat Mar 28 12:01:47 EDT 2009
details: http://project.geeklog.net/cgi-bin/hgweb.cgi/rev/f90390360557
changeset: 6859:f90390360557
user: Dirk Haun <dirk at haun-online.de>
date: Sat Mar 28 14:15:00 2009 +0100
description:
Documentation updates
diffstat:
10 files changed, 156 insertions(+), 83 deletions(-)
public_html/admin/moderation.php | 21 ++
public_html/admin/plugins/staticpages/index.php | 8 -
public_html/directory.php | 2
public_html/usersettings.php | 14 +
system/lib-plugins.php | 172 +++++++++++++++--------
system/lib-security.php | 6
system/lib-story.php | 4
system/lib-trackback.php | 2
system/lib-user.php | 2
system/lib-webservices.php | 8 -
diffs (truncated from 735 to 300 lines):
diff -r b09db899c7dc -r f90390360557 public_html/admin/moderation.php
--- a/public_html/admin/moderation.php Sat Mar 28 10:31:38 2009 +0100
+++ b/public_html/admin/moderation.php Sat Mar 28 14:15:00 2009 +0100
@@ -72,7 +72,9 @@
/**
* Prints the command & control block at the top
*
-* TODO: The moderation items should be displayed with the help of ul/li
+* @param string $token CSRF token
+* @return string HTML for the C&C block
+* @todo The moderation items should be displayed with the help of ul/li
* instead of div's.
*
*/
@@ -233,7 +235,9 @@
*
* Displays the moderation list of items from the submission tables
*
-* @type string Type of object to build list for
+* @param string $type Type of object to build list for
+* @param string $token CSRF token
+* @return string HTML for the list of items
*
*/
function itemlist($type, $token)
@@ -333,8 +337,11 @@
* site membership. When approving an application, an email containing the
* password is sent out immediately.
*
+* @param string $token CSRF token
+* @return string HTML for the list of users
+*
*/
-function userlist ($token)
+function userlist($token)
{
global $_CONF, $_TABLES, $LANG29, $LANG_ADMIN;
@@ -396,8 +403,11 @@
* 'draft'. Approving a story from this list will clear the draft flag and
* thus publish the story.
*
+* @param string $token CSRF token
+* @return string HTML for the list of draft stories
+*
*/
-function draftlist ($token)
+function draftlist($token)
{
global $_CONF, $_TABLES, $LANG24, $LANG29, $LANG_ADMIN;
@@ -643,8 +653,9 @@
/**
* Display a reminder to execute the security check script
*
+* @return string HTML for security reminder (or empty string)
*/
-function security_check_reminder ()
+function security_check_reminder()
{
global $_CONF, $_TABLES, $_IMAGE_TYPE, $MESSAGE;
diff -r b09db899c7dc -r f90390360557 public_html/admin/plugins/staticpages/index.php
--- a/public_html/admin/plugins/staticpages/index.php Sat Mar 28 10:31:38 2009 +0100
+++ b/public_html/admin/plugins/staticpages/index.php Sat Mar 28 14:15:00 2009 +0100
@@ -440,11 +440,13 @@
/**
* Displays the Static Page Editor
*
-* @sp_id string ID of static page to edit
-* @mode string Mode
+* @param string $sp_id ID of static page to edit
+* @param string $mode Mode
+* @param string $editor Editor mode? (unused?)
+* @return string HTML for static pages editor
*
*/
-function staticpageeditor ($sp_id, $mode = '', $editor = '')
+function staticpageeditor($sp_id, $mode = '', $editor = '')
{
global $_CONF, $_TABLES, $_USER;
diff -r b09db899c7dc -r f90390360557 public_html/directory.php
--- a/public_html/directory.php Sat Mar 28 10:31:38 2009 +0100
+++ b/public_html/directory.php Sat Mar 28 14:15:00 2009 +0100
@@ -68,7 +68,7 @@
* @param int $month Month
* @param int $year Year
* @return int Number of days in that month
-* @bugs Will fail from 2038 onwards ...
+* @todo Bug: Will fail from 2038 onwards ...
*
* "The last day of any given month can be expressed as the "0" day
* of the next month", http://www.php.net/manual/en/function.mktime.php
diff -r b09db899c7dc -r f90390360557 public_html/usersettings.php
--- a/public_html/usersettings.php Sat Mar 28 10:31:38 2009 +0100
+++ b/public_html/usersettings.php Sat Mar 28 14:15:00 2009 +0100
@@ -2,13 +2,13 @@
/* Reminder: always indent with 4 spaces (no tabs). */
// +---------------------------------------------------------------------------+
-// | Geeklog 1.5 |
+// | Geeklog 1.6 |
// +---------------------------------------------------------------------------+
// | usersettings.php |
// | |
// | Geeklog user settings page. |
// +---------------------------------------------------------------------------+
-// | Copyright (C) 2000-2008 by the following authors: |
+// | Copyright (C) 2000-2009 by the following authors: |
// | |
// | Authors: Tony Bibbs - tony AT tonybibbs DOT com |
// | Mark Limburg - mlimburg AT users DOT sourceforge DOT net |
@@ -853,7 +853,8 @@
/**
* Saves the user's information back to the database
*
-* @A array User's data
+* @param array $A User's data
+* @return string HTML error message or meta redirect
*
*/
function saveuser($A)
@@ -899,7 +900,7 @@
function_exists ('CUSTOM_userCheck')) {
$ret = CUSTOM_userCheck ($A['username'], $A['email']);
if (!empty($ret)) {
- // Need a numeric return for the default message hander
+ // Need a numeric return for the default message handler
// - if not numeric use default message
if (!is_numeric($ret['number'])) {
$ret['number'] = 400;
@@ -911,7 +912,7 @@
function_exists ('CUSTOM_userCheck')) {
$ret = CUSTOM_userCheck ($A['username'], $A['email']);
if (!empty($ret)) {
- // Need a numeric return for the default message hander
+ // Need a numeric return for the default message handler
// - if not numeric use default message
if (!is_numeric($ret['number'])) {
$ret['number'] = 400;
@@ -1323,7 +1324,8 @@
/**
* Saves user's preferences back to the database
*
-* @A array User's data to save
+* @param array $A User's data to save
+* @return void
*
*/
function savepreferences($A)
diff -r b09db899c7dc -r f90390360557 system/lib-plugins.php
--- a/system/lib-plugins.php Sat Mar 28 10:31:38 2009 +0100
+++ b/system/lib-plugins.php Sat Mar 28 14:15:00 2009 +0100
@@ -42,21 +42,30 @@
die('This file can not be used on its own!');
}
+/**
+* Include plugin class
+*/
require_once $_CONF['path_system'] . 'classes/plugin.class.php';
-// Response codes for the service invocation PLG_invokeService()
-define('PLG_RET_OK', 0);
-define('PLG_RET_ERROR', -1);
-define('PLG_RET_PERMISSION_DENIED', -2);
-define('PLG_RET_AUTH_FAILED', -3);
-define('PLG_RET_PRECONDITION_FAILED', -4);
+/**
+* Response codes for the service invocation PLG_invokeService(). Note that
+* these are intentionally vague so as not to give away too much information.
+*/
+define('PLG_RET_OK', 0); // success
+define('PLG_RET_ERROR', -1); // generic error
+define('PLG_RET_PERMISSION_DENIED', -2); // access to item or object denied
+define('PLG_RET_AUTH_FAILED', -3); // authentication failed
+define('PLG_RET_PRECONDITION_FAILED', -4); // a precondition was not met
// buffer for function names for the center block API
-$PLG_bufferCenterAPI = array ();
+$PLG_bufferCenterAPI = array();
$PLG_buffered = false;
// buffer enabled plugins
$result = DB_query("SELECT pi_name FROM {$_TABLES['plugins']} WHERE pi_enabled = 1");
+/**
+* @global array List of all active plugins
+*/
$_PLUGINS = array();
while ($A = DB_fetchArray($result)) {
$_PLUGINS[] = $A['pi_name'];
@@ -65,7 +74,9 @@
/**
* Calls a function for all enabled plugins
*
-* @param string $function_name holds name of function to call
+* @param string $function_name holds name of function to call
+* @return void
+* @internal not to be used by plugins
*
*/
function PLG_callFunctionForAllPlugins($function_name)
@@ -95,6 +106,7 @@
* @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
+* @internal not to be used by plugins
*
*/
function PLG_callFunctionForOnePlugin($function, $args='')
@@ -140,10 +152,12 @@
}
/**
-* Tells a plugin to install itself. NOTE: not currently used anymore
+* Tells a plugin to install itself. NOTE: not currently used any more
*
-* @param string $type Plugin name
-* @return boolean Returns true on success otherwise false
+* @param string $type Plugin name
+* @return boolean Returns true on success otherwise false
+* @deprecated deprecated since Geeklog 1.6.0
+* @link http://wiki.geeklog.net/index.php/Plugin_Autoinstall
*
*/
function PLG_install($type)
@@ -169,6 +183,7 @@
* @param string $type Plugin name
* @param array $old_conf contents of $_CONF before the migration
* @return boolean true on success, otherwise false
+* @link http://wiki.geeklog.net/index.php/PLG_migrate
*
*/
function PLG_migrate($type, $old_conf)
@@ -199,8 +214,9 @@
/**
* Tells a plugin to uninstall itself.
*
-* @param string $type Plugin to uninstall
-* @return boolean Returns true on success otherwise false
+* @param string $type Plugin to uninstall
+* @return boolean Returns true on success otherwise false
+* @link http://wiki.geeklog.net/index.php/Plugin_Auto-Uninstall
*
*/
function PLG_uninstall ($type)
@@ -823,10 +839,12 @@
* The plugin has to provide an array for the menuitem of the format:
* array (menuitem_title, item_url, submission_count)
* 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))
+* </code>
* Plugin function can return a single record array or multiple records
*
*
@@ -839,6 +857,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
+* @internal not to be used by plugins
*
*/
function PLGINT_getOptionsforMenus($var_names, $required_names, $function_name)
@@ -895,12 +914,16 @@
* This supports that a plugin can have several lines in the CC menu.
* The plugin has to provide simply a set arrays with 3 variables in order to
* get n lines in the menu such as
+* <code>
* array(
* array("first line", "url1", "1"),
* array("second line", "url2", "44"),
* etc, etc)
+* </code>
* If there is only one item, a single array is enough:
+* <code>
* array("first line", "url1", "1")
+* </code>
*
* @return array Returns Command and Control options for moderation.php
*
@@ -924,12 +947,16 @@
* This supports that a plugin can have several lines in the Admin menu.
* The plugin has to provide simply a set arrays with 3 variables in order to
* get n lines in the menu such as
+* <code>
* array(
* array("first line", "url1", "1"),
* array("second line", "url2", "44"),,
* etc, etc)
+* </code>
* If there is only one item, a single array is enough:
+* <code>
* array("first line", "url1", "1")
+* </code>
*
More information about the geeklog-cvs
mailing list