From f1aa9f3f6d4798f26d23689fe8cb2c9c4e9a7afc Mon Sep 17 00:00:00 2001 From: Robert Sesek Date: Sun, 17 Apr 2005 05:05:06 +0000 Subject: [PATCH] Making everything properly documented so that we don't produce warnings when running ./phpdoc.sh --- db_mysql.php | 90 ++++++++++++++++++++++++++++++++++++------------- functions.php | 39 ++++++++++++++++----- kernel.php | 83 +++++++++++++++++++++++++++++++++++---------- mail.php | 48 +++++++++++++++++++++----- phpdoc.sh | 31 +++++++++++++++++ template.php | 79 +++++++++++++++++++++++++++++++++++-------- template_fs.php | 21 +++++++++--- xml.php | 65 +++++++++++++++++++++++++++++------ 8 files changed, 371 insertions(+), 85 deletions(-) create mode 100755 phpdoc.sh diff --git a/db_mysql.php b/db_mysql.php index 3ffc10e..7d3406c 100644 --- a/db_mysql.php +++ b/db_mysql.php @@ -10,6 +10,13 @@ || ################################################################### || \*=====================================================================*/ +/** +* MySQL Database Abstraction Layer +* db_mysql.php +* +* @package ISSO +*/ + $OBJECT = 'MySQL Database Abstraction Layer'; $CLASS = 'MySQL_Database_Driver'; $OBJ = 'db'; @@ -23,29 +30,64 @@ $OBJ = 'db'; * @author Iris Studios, Inc. * @copyright Copyright ©2002 - [#]year[#], Iris Studios, Inc. * @version $Revision$ +* @package ISSO * */ class MySQL_Database_Driver { /** - * Global environment variables - * - * @var database The name of the MySQL database used - * @var errshow Report errors durring execution? - * @var errno Current error number - * @var errstr Description of the current error - * @var link_id Link-ID for current connexion - * @var query_id Current query ID - * @var query_str Current query string - * @var history A list of all query reporting information + * Database that is used in the application + * @var str + * @see connect() */ var $database = ''; + + /** + * Determines whether or not errors should be shown + * @var bool + * @see error() + */ var $errshow = true; - var $errno = 0; - var $errstr = ''; - var $link_id = 0; - var $query_id = 0; + + /** + * Current error number + * @var int + * @see error() + */ + var $error_no = 0; + + /** + * Description of current error + * @var str + * @see error() + */ + var $error_str = ''; + + /** + * Currend open MySQL connexion + * @var res + * @see connect() + */ + var $link_id = null; + + /** + * Current query ID + * @var res + * @see query() + */ + var $query_id = null; + + /** + * Current query string + * @var str + * @see query() + */ var $query_str = ''; + + /** + * History of all executed queryies + * @var array + */ var $history = array(); /** @@ -133,7 +175,7 @@ class MySQL_Database_Driver /** * Fetch the query result as an array * - * @param res Query-ID + * @param res Query ID * * @return array A row of the query result */ @@ -145,7 +187,7 @@ class MySQL_Database_Driver /** * Fetch the query result as an object * - * @param res Query-ID + * @param res Query ID * * @return obj An object with the query result */ @@ -157,7 +199,7 @@ class MySQL_Database_Driver /** * Free the current MySQL query result * - * @param res Query-ID + * @param res Query ID */ function free_result($query_id) { @@ -195,7 +237,7 @@ class MySQL_Database_Driver /** * Fetch the number of rows in the result * - * @param res Query-ID + * @param res Query ID * * @return int Number of MySQL rows */ @@ -207,6 +249,8 @@ class MySQL_Database_Driver /** * Fetch the number of rows affected by the query * + * @param res Query ID + * * @return int Number of affected rows */ function affected_rows($query_id) @@ -217,7 +261,7 @@ class MySQL_Database_Driver /** * MySQL error wrapper for ISSO::_message() * - * @param str User-defined error message + * @param str User defined error message */ function error($message) { @@ -227,16 +271,16 @@ class MySQL_Database_Driver { if ($this->link_id) { - $this->errno = mysql_errno($this->link_id); - $this->errstr = mysql_error($this->link_id); + $this->error_no = mysql_error_no($this->link_id); + $this->error_str = mysql_error($this->link_id); } $style['code'] = 'font-family: \'Courier New\', Courier, mono; font-size: 11px;'; $message_prepped = "
\n

"; $message_prepped .= "\n\t» Query:\n

" . $this->query_str ."
\n
"; - $message_prepped .= "\n\t» Error Number: " . $this->errno . "\n
"; - $message_prepped .= "\n\t» Error Message: " . $this->errstr . "\n
"; + $message_prepped .= "\n\t» Error Number: " . $this->error_no . "\n
"; + $message_prepped .= "\n\t» Error Message: " . $this->error_str . "\n
"; $message_prepped .= "\n\t» Additional Notes: " . $message . "\n
"; $message_prepped .= "\n\t» File: " . $_SERVER['PHP_SELF'] . "\n"; $message_prepped .= "\n

\n
"; diff --git a/functions.php b/functions.php index 7aa1a6c..96cceef 100644 --- a/functions.php +++ b/functions.php @@ -10,12 +10,19 @@ || ################################################################### || \*=====================================================================*/ +/** +* Globalized Functions +* functions.php +* +* @package ISSO +*/ + $OBJECT = 'Core Functions'; $CLASS = 'Functions'; $OBJ = 'funct'; /** -* Globalized function framework +* Globalized Functions * * This framework is a set of functions that are commonly used in most * applications. @@ -23,21 +30,37 @@ $OBJ = 'funct'; * @author Iris Studios, Inc. * @copyright Copyright ©2002 - [#]year[#], Iris Studios, Inc. * @version $Revision$ -* +* @package ISSO +* */ class Functions { /** - * Global environment variables - * - * @var cookiepath The path for cookies - * @var cookiedom Cookie domain - * @var cookieexp The time in which a cookie will expire - * @var bgcolour Current background colour of the alternation system + * The path that is used to set cookies + * @var str + * @see cookie() */ var $cookiepath = '/'; + + /** + * The domain used for cookie setting + * @var str + * @see cookie() + */ var $cookiedom = ''; + + /** + * The time it takes for a cookie to expire + * @var int + * @see cookie() + */ var $cookieexp = 900; + + /** + * State of the current background colour during alternation + * @var str + * @see exec_swap_bg() + */ var $bgcolour = ''; /** diff --git a/kernel.php b/kernel.php index 5e49f50..c64a906 100644 --- a/kernel.php +++ b/kernel.php @@ -10,6 +10,13 @@ || ################################################################### || \*=====================================================================*/ +/** +* Iris Studios Shared Object Framework Kernel +* kernel.php +* +* @package ISSO +*/ + if (PHP_VERSION < '4.1.0') { trigger_error('You need PHP version 4.1.0 or newer to run ISSO', E_USER_ERROR); @@ -80,41 +87,83 @@ if ((bool)ini_get('register_globals') === true) * @author Iris Studios, Inc. * @copyright Copyright ©2002 - [#]year[#], Iris Studios, Inc. * @version $Revision$ +* @package ISSO * */ class Shared_Object_Framework { /** - * Global environment variables - * - * This is where we keep the global variables that are used within the shared framework - * - * @var version ISSO version - * @var sourcepath The location of the framework sources - * @var appath The path to the application's location - * @var application The name of the application that is using the framework - * @var appversion The version of the application - * @var debug Variable for debug mode - * @var debuginfo Listing of all debug notices - * @var modules An array of loaded framework modules - * @var input All input data for the system - * @var i Short-hand reference to $isso::input - * @var in Short-hand reference to $isso::input - * @var magicquotes Status of Magic Quotes GPC - * @var escapestrings Sets whether or not we escape strings automatically + * ISSO version + * @var str */ var $version = '[#]version[#]'; + + /** + * Location of ISSO, used for internal linking + * @var str + * @see fetch_sourcepath(), load(), locate() + */ var $sourcepath = ''; + + /** + * Path of the current application + * @var str + */ var $apppath = ''; + + /** + * Name of the current application + * @var str + */ var $application = ''; + + /** + * Version of the current application + * @var str + */ var $appversion = ''; + + /** + * Whether debug mode is on or off + * @var bool + */ var $debug = false; + + /** + * List of all active debug messages + * @var array + * @see debug() + */ var $debuginfo = array(); + + /** + * List of loaded modules + * @var array + * @see load(), show_modules() + */ var $modules = array(); + + /** + * An array of sanitized variables that have been cleaned for HTML tag openers and double quotes + * @var array + * @see sanitize(), exec_sanitize_data() + */ var $input = array(); var $i = array(); var $in = array(); + + /** + * If we are running with magic_quotes_gpc on or off + * @var int + * @see escape(), exec_sanitize_data() + */ var $magicquotes = 0; + + /** + * If we should automagically escape strings, mimicking magic_quotes_gpc + * @var bool + * @see exec_sanitize_data() + */ var $escapestrings = false; /** diff --git a/mail.php b/mail.php index 051bbb3..00e5e8b 100644 --- a/mail.php +++ b/mail.php @@ -10,6 +10,13 @@ || ################################################################### || \*=====================================================================*/ +/** +* Mail Sender +* mail.php +* +* @package ISSO +*/ + $OBJECT = 'Mail Sender'; $CLASS = 'Mail'; $OBJ = 'mail'; @@ -23,25 +30,50 @@ $OBJ = 'mail'; * @author Iris Studios, Inc. * @copyright Copyright ©2002 - [#]year[#], Iris Studios, Inc. * @version $Revision$ +* @package ISSO * */ class Mail { /** - * Global environment variables - * - * @var to The recipient - * @var subject Subject of the message - * @var body Text/body of the email - * @var from The sender's email - * @var fromname The sender's name - * @var headers Additional headers + * The message recipient's email address + * @var str + * @see send() */ var $to = ''; + + /** + * The subject of the message + * @var str + * @see send() + */ var $subject = ''; + + /** + * Body of the message + * @var str + * @see send() + */ var $body = ''; + + /** + * The message sender's email address + * @var str + * @see send() + */ var $from = ''; + + /** + * The message sender's display name + * @var str + * @see send() + */ var $fromname = ''; + + /** + * Additional message headers + * @var str + */ var $headers = ''; /** diff --git a/phpdoc.sh b/phpdoc.sh new file mode 100755 index 0000000..d133bca --- /dev/null +++ b/phpdoc.sh @@ -0,0 +1,31 @@ +#!/bin/sh + +# SVN $Id$ + +rm -rf ./apidoc/* + +################# +## OUTPUT LIST ## +################# +# HTML:frames:default (purple, white) +# HTML:frames:phpdoc.de (grey, tonal) +# HTML:frames:phphtmllib (grey, blue, red) +# HTML:frames:DOM/XX (JS: replace XX with above options) +# HTML:Smarty:PHP (php.net style) +# PDF:default:default (PDF, ugly) + +################## +## OPTIONS LIST ## +################## +# parse/directory +# target/result +# ignore +# do hidden files +# title +# parse private +# default name/package +# default category +# hilight source code +# output options + +phpdoc -d . -t ./apidoc -i _*.php -dh off -ti "Iris Studios Shared Object Framework" -pp on -dn ISSO -dc ISSO -s off -o HTML:frames:phphtmllib > ./apidoc/log.txt \ No newline at end of file diff --git a/template.php b/template.php index 6ed1086..b7e8f6b 100644 --- a/template.php +++ b/template.php @@ -10,6 +10,13 @@ || ################################################################### || \*=====================================================================*/ +/** +* Database-Driven Template System +* template.php +* +* @package ISSO +*/ + $OBJECT = 'Database Template System'; $CLASS = 'DB_Template'; $OBJ = 'template'; @@ -23,35 +30,79 @@ $OBJ = 'template'; * @author Iris Studios, Inc. * @copyright Copyright ©2002 - [#]year[#], Iris Studios, Inc. * @version $Revision$ +* @package ISSO * */ class DB_Template { /** - * Global environment variables - * - * This stores all of the cached and parsed template data - * - * @var tablename The name of the database table templates are in - * @var namecolumn The name of the database column template names are in - * @var datacolumn The name of the database column template data is stored in - * @var extrawhere Additional information for the WHERE clause in template loading - * @var langcall Function wrapper for phrase fetching system - * @var langconst Function that constructs a phrase with sprintf() - * @var cache Stores all fettched templates - * @var usage Counter for template usage - * @var uncached List of uncached templates - * @var doneflush Variable to check and see if output has been sent + * Name of the database table templates are in + * @var str + * @see _load() */ var $templatetable = ''; + + /** + * Name of the table column template names are in + * @var str + * @see $templatetable, _load() + */ var $namecolumn = ''; + + /** + * Name of the table column templates are in + * @var str + * @see templatetable, _load() + */ var $datacolumn = ''; + + /** + * Additional WHERE clauses for the template fetch SQL + * @var str + * @see _load(), cache() + */ var $extrawhere = ''; + + /** + * The name of the function phrases are fetched with + * @var str + * @see _parse_phrases() + */ var $langcall = 'fetch_phrase'; + + /** + * The name of the function phrases are sprintf() parsed with + * @var str + * @see _parse_phrases() + */ var $langconst = 'construct_phrase'; + + /** + * Array of pre-compiled templates that are stored to decrease server load + * @var array + * @see cache() + */ var $cache = array(); + + /** + * A list of the number of times each template has been used + * @var array + * @see fetch() + */ var $usage = array(); + + /** + * A list of templates that weren't cached, but are still used + * @var array + * @see fetch() + */ var $uncached = array(); + + /** + * Whether or not the page has been flush()'d already + * @var bool + * @see flush() + */ var $doneflush = false; /** diff --git a/template_fs.php b/template_fs.php index 070f214..97a3090 100644 --- a/template_fs.php +++ b/template_fs.php @@ -10,6 +10,13 @@ || ################################################################### || \*=====================================================================*/ +/** +* File System Template System +* template_fs.php +* +* @package ISSO +*/ + if (!$this->is_loaded('template')) { $this->locate('template'); @@ -28,17 +35,23 @@ $OBJ = 'template'; * @author Iris Studios, Inc. * @copyright Copyright ©2002 - [#]year[#], Iris Studios, Inc. * @version $Revision$ +* @package ISSO * */ class FS_Template extends DB_Template { /** - * Global environment variables - * - * @var templatedir Directory name that houses the templates - * @var extension The extension used on template files + * The path, from the path of the application, where templates are stored + * @var str + * @see Shared_Object_Framework::$apppath, _load() */ var $templatedir = ''; + + /** + * The extension all the template files have + * @var str + * @see _load() + */ var $extension = 'tpl'; /** diff --git a/xml.php b/xml.php index da6f20e..fa275f8 100644 --- a/xml.php +++ b/xml.php @@ -10,6 +10,13 @@ || ################################################################### || \*=====================================================================*/ +/** +* XML Parser +* xml.php +* +* @package ISSO +*/ + $OBJECT = 'XML Parser'; $CLASS = 'XML_Parser'; $OBJ = 'xml'; @@ -22,31 +29,67 @@ $OBJ = 'xml'; * @author Iris Studios, Inc. * @copyright Copyright ©2002 - [#]year[#], Iris Studios, Inc. * @version $Revision$ +* @package ISSO * */ class XML_Parser { /** - * Global environment variables - * - * @var parser Current XML parser - * @var taginfo Array of all the processed tag data - * @var taghandler What to do for each tag encountered - * @var trimdata Trim CDATA elements? - * @var attrdata Data parsed from global attributes - * @var tagid Current tag ID in the document - * @var tagname Current tag name in the document - * @var tree Tag stack to use for proper nesting - * @var parent The tag's parent + * Parser resource + * @var res + * @see parse() */ var $parser = null; + + /** + * Array of all parsed tag data + * @var array + */ var $taginfo = array(); + + /** + * An array of function names that are to be executed for each tag name (name => function) + * @var array() + * @see parse() + */ var $taghandler = array(); + + /** + * Whether we should trim CDATA elements + * @var bool + * @see parse() + */ var $trimdata = true; + + /** + * Attribute data parsed from the tags + * @var array + * @see _tag_start() + */ var $attrdata = array(); + + /** + * Internal tracker for the current tag + * @var int; + */ var $tagid = -1; + + /** + * Internal tracker for the name of the current tag + * @var str + */ var $tagname = ''; + + /** + * An internal tree to sort out the nesting of elements + * @var array + */ var $tree = array(); + + /** + * Internal tracker for the tag above the current one + * @var int + */ var $parent = -1; /** -- 2.22.5