<?
/***************************************************************************
Mdoc.php
--------------
A PHP4 class to build class (or library) documentation from code.
$Revision: 1.4 $
$Date: 2006/01/10 15:26:43 $
$Author: jmfaure $
/
/ Copyright (c) 2005, JM Faure
/ <jmfaure@users.sourceforge.net>
o/
| >----- Redistribution and use in source and binary forms,
o / with or without modification, are permitted provided
/ that the BSD License conditions are met, please
/ refer to: www.opensource.org/licenses/bsd-license.php
**************************************************************************/
// Ensure this script is included by a parent file
if (realpath($_SERVER['SCRIPT_FILENAME']) == __FILE__) die("FILE ACESS METHOD NOT ALLOWED");
/**
* Return flags for getdoc_ and getnav_ methods.
*
* These getdoc_ and getnav_ methods render the documentation in a nice output
* format thru a powerful template rendering feature. To help in creating and
* maintaining the templates, they can be called with their MDOC_RETURN_TEMPLATE
* flag set so they will return the template "as is", after eventual customization
* but without rendering.
*/
define("MDOC_RETURN_NORMAL", 0); // return normal renderered output
define("MDOC_RETURN_TEMPLATE", 1); // return the template array
/**
* Build class or library documentation from PHP source code.
*
* Mdoc is an auto-documentation tool to create manuals like PHP manual at
* php.net web site, so in a style common to the PHP community and is very
* efficient to share your code as APIs.
*
* Mdoc parses the PHP source code and its comments to build the manual
* for a class or a library. A class is a valid PHP4 or PHP5 class, a
* library is file of functions, both may contains constant declarations.
*
* Documentation may then be displayed formated in hard-coded or custom
* (X)HTML code which can be included in web pages. Hard-coded format style
* is mostly inspired from PHP manual at php.net web site.
*
* Custom format is built thanks to a powerful template feature and can
* be in any structured language such like XML (assuming the template smart
* display flag is set to "off" to disable the XHTML smart display feature).
*/
class Mdoc {
/**
* Stack to store data elements when fetching template.
*
* Data element contains source code documentation which may contain
* {TEMPLATE_LIKE} strings which could confuse recursive subtsitutions.
* So this array will store every data element values which are fetch
* in the last subtsitution pass.
*
* @private
* @type array
*/
var $fetch_data = array();
/**
* The code source file name.
*
* @private
* @type string
*/
var $filename;
/**
* Stack of parsing error messages.
*
* Error messages are appended to the log stack while code source
* is parsed to build the documentation tree. Most of messages try
* to help the user in correcting and completing code comments
* (like a code compiler would do).
*
* @private
* @type array
*/
var $parser_log = array();
/**
* Source code to process (with comments).
*
* @private
* @type string
*/
var $source;
/**
* Source code without comments.
*
* @private
* @type string
*/
var $stripped_code;
/**
* Stack of template handling messages.
*
* Template messages are appended to the log while methods try
* to fill template elements. Most of messages try to help the
* user in building efficient templates to output documentation.
*
* @private
* @type array
*/
var $template_log = array();
/**
* The class (or library) documentation in a tree structure.
*
* @private
* @type array
*/
var $tree = array();
/**
* Load and store PHP source code to document.
*
* When an instance is created, the source code is loaded from the file
* in the $source property and the code without comments is stored in the
* $stripped_code property.
*
* The source file n chars are converted into server n to ensure Windows, Mac
* and Unix source code compliance.
*
* @param (string) $file filename to process (to build the documentation)
* @return (object) an instance of Mdoc
*/
function Mdoc($file) {
// Load the source related to the input type
if (!file_exists($file)) {
trigger_error("file <i>$file</i> doesn't exist", E_USER_ERROR);
return;
}
$this->filename = $file;
$this->source = file_get_contents($file);
// Avoid n issue, converting n from Windows, Mac or Unix source to server n
$this->source = preg_replace('!rn|r|n!', "n", $this->source);
// Save also code without comments
$this->stripped_code = $this->uparse_removecomments($this->source);
}
/*****************************************************************************/
/* */
/* HTML output formating methods */
/* */
/*****************************************************************************/
/**
* Return the documentation of the current class.
*
* This method builds the documentation page for the class found in the current
* source code file. A native XHTML template is hard-coded to render the page
* in the php.net manual style.
*
* The $template parameter can be used to redefine some custom template elements
* or to redefine the whole template. Thus you can create a template for CHM,
* PDF or XML output asuming you set the template FLAG:smart_display "off".
*
* By default, the documentation is returned rendered, but the MDOC_RETURN_TEMPLATE
* flag can be set to return the template "as is" after customization with the
* elements passed in $template parameter.
*
* To build your own template, see the template technical reference page.
*
* This method implements the following error messages:
* 'ERRMSG:language_not_supported' => class must be coded in PHP
* 'ERRMSG:not_a_class' => method called on a file which is not a class
*
* If not already done, this method builds the documentation internal tree.
*
* @param (string) $view set to 'public' to view only API usage details,
* set to 'author' (default value) to view all details
* @param (array) $template optional custom template hooks
* @param (int) $flag set to MDOC_RETURN_TEMPLATE to get the template associative
* array which may be useful to get the hard-coded template
* elements or to help in building custom elements,
* set to MDOC_RETURN_NORMAL (default value) to get a nice
* document page rendered within native or custom template
* @return (string) the class "formated" documentation page
* (string) an error message if the documentation page can't be built
* (array) the template array if the flag MDOC_RETURN_TEMPLATE is set
*/
function getdoc_class($view = "author", $template = array(), $flag = MDOC_RETURN_NORMAL) {
// Parse file into documentation tree if not done yet
if (empty($this->tree)) $this->parse();
// Ensure working on a valid PHP class
$language = empty($this->tree['main']['language']) ?
"unknown" :
$this->tree['main']['language'];
if ($language != "PHP") {
$err = empty($template['ERRMSG:language_not_supported']) ?
"Current code language ($language) isn't supported." :
$template['ERRMSG:language_not_supported'];
return $err;
}
$type = empty($this->tree['main']['type']) ?
"unknown" :
$this->tree['main']['type'];
if (!in_array($type, array("class", "abstract_class", "final_class", "interface"))) {
$err = empty($template['ERRMSG:not_a_class']) ?
"Current file isn't coding a class (type is $type)." :
$template['ERRMSG:not_a_class'];
return $err;
}
// Set hard-coded template, author view first
$tpl['VIEW:author'] =
"<h1>{TREE.main.name}</h1>n" .
"<p>Class {TREE.main.name} -- {TREE.main.description.short}</p>n" .
"{TREE.main.source.extends?not_blank}" .
"{TREE.main.source.implements?not_blank}" .
"{TREE.main.info?not_blank}" .
"{TREE.main.info.warning?not_blank}" .
"{TREE.main.description.long?not_blank}" .
"{TREE.main.info.experimental?not_blank}" .
"<h2>Methods</h2>n" .
"{TREE.method?not_blank}" .
"{TREE.property?not_blank}" .
"{TREE.main.constants?not_empty}" .
"{TREE.cvs?not_blank}";
// Public view
$tpl['VIEW:public'] =
"<h1>{TREE.main.name}</h1>n" .
"<p>Class {TREE.main.name} -- {TREE.main.description.short}</p>n" .
"{TREE.main.source.extends?not_blank}" .
"{TREE.main.source.implements?not_blank}" .
"{TREE.main.info.warning?not_blank}" .
"{TREE.main.description.long?not_blank}" .
"{TREE.main.info.experimental?not_blank}" .
"<h2>Methods</h2>n" .
"{TREE.public_method#public?not_blank}" .
"{TREE.public_property#public?not_blank}" .
"{TREE.main.constants?not_empty}";
// Long description if not blank (?blank not required, default is "")
$tpl['TREE.main.description.long?not_blank'] =
"<h2>Description</h2>n" .
"<p>{TREE.main.description.long}</p>n";
// Inheritance
$tpl['TREE.main.source.extends?not_blank'] = "<p>This class inherits from {EXTENDS_URL} class.</p>n";
$tpl['EXTENDS_URL'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?class={TREE.main.source.extends}" .
"&view={VIEW}" class="classurl">{TREE.main.source.extends}</a>";
// Interfaces
$tpl['TREE.main.source.implements?not_blank'] = "<p>This class implements interfaces: {TREE.main.source.implements}.</p>n";
$tpl['TREE.main.source.implements:frame'] = "{TREE.main.source.implements:any}";
$tpl['TREE.main.source.implements:first'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?class={IMPLEMENTS%Value}" .
"&view={VIEW}" class="classurl">{IMPLEMENTS%Value}</a>";
$tpl['TREE.main.source.implements:any'] =
", <a href="" . $_SERVER['PHP_SELF'] . "?class={IMPLEMENTS%Value}" .
"&view={VIEW}" class="classurl">{IMPLEMENTS%Value}</a>";
// Optional CVS keywords (revision log excluded)
$tpl['TREE.cvs?not_blank'] = "{TREE.cvs}";
$tpl['TREE.cvs:frame'] =
"<h2>CVS</h2>n" .
"<p>This source code file has some CVS keywords expanded:</p>n" .
"<table class="cvsinfo">n{TREE.cvs:any}</table>n";
$tpl['TREE.cvs:any'] = "<tr><td>{CVS%Keyword}: </td><td> {CVS%Value}</td></tr>n";
$tpl['TREE.cvs:exclude'] = array('Log');
// Main infos
$tpl['TREE.main.info?not_blank'] = "{TREE.main.info}";
$tpl['TREE.main.info:frame'] =
"<table class="classinfo">n" .
"<tr><td colspan="2">Author informations</td></tr>n" .
"{TREE.main.info:any}" .
"</table>n";
$tpl['TREE.main.info:any'] = "<tr><td>@{INFO%Keyword} </td><td> {INFO%Value}</td></tr>n";
$tpl['TREE.main.info:exclude'] = array("experimental", "warning");
// Warning
$tpl['TREE.main.info.warning?not_blank'] = "<p><b>Warning: {TREE.main.info.warning}</b></p>n";
// Experimental status
$tpl['TREE.main.info.experimental?not_blank'] =
"<table class="warning" border="1" width="100%">n" .
"<tr><td align="center"><b>Warning</b></td></tr>n" .
"<tr><td align="left"><p>This class is <span class="emphasis">" .
"<i class="emphasis">EXPERIMENTAL</i></span>.n" .
"The behaviour of this class, the name of this class, and anythingn" .
"else documented about this class may change without notice in a futuren" .
"release.</p></td></tr>n</table>n";
// Methods
$tpl['TREE.method?not_blank'] =
"{TREE.public_method?not_blank}" .
"{TREE.private_method?not_blank}" .
"{TREE.protected_method?not_blank}";
$tpl['TREE.method?blank'] = "<p>This class has no methods defined.</p>n";
// Public methods
$tpl['TREE.public_method?not_blank'] =
"<h3>Public methods</h3>n" .
"<dl>n" .
"{TREE.public_method}" .
"</dl>n";
$tpl['TREE.public_method?blank'] =
"<h3>Public methods</h3>n" .
"<p>This class has no public methods defined.</p>n";
$tpl['TREE.public_method:frame'] = "{TREE.public_method:any}";
$tpl['TREE.public_method:any'] =
" <dt>{PUBLIC_METHOD_URL} -- {PUBLIC_METHOD.description.short}</dt>n";
$tpl['PUBLIC_METHOD_URL'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?class={TREE.main.name}&method={PUBLIC_METHOD}" .
"&view={VIEW}" class="methodurl">{PUBLIC_METHOD}</a>";
// -- for "public" view
$tpl['TREE.public_method#public?not_blank'] =
"<dl>n" .
"{TREE.public_method}" .
"</dl>n";
$tpl['TREE.public_method#public?blank'] =
"<p>This class has no public methods defined.</p>n";
// Private methods
$tpl['TREE.private_method?not_blank'] =
"<h3>Private methods</h3>n" .
"<dl>n" .
"{TREE.private_method}" .
"</dl>n";
$tpl['TREE.private_method?blank'] =
"<h3>Private methods</h3>n" .
"<p>This class has no private methods defined.</p>n";
$tpl['TREE.private_method:frame'] = "{TREE.private_method:any}";
$tpl['TREE.private_method:any'] =
" <dt>{PRIVATE_METHOD_URL} -- {PRIVATE_METHOD.description.short}</dt>n";
$tpl['PRIVATE_METHOD_URL'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?class={TREE.main.name}&method={PRIVATE_METHOD}" .
"&view={VIEW}" class="methodurl">{PRIVATE_METHOD}</a>";
// Protected methods
$tpl['TREE.protected_method?not_blank'] =
"<h3>Protected methods</h3>n" .
"<dl>n" .
"{TREE.protected_method}" .
"</dl>n";
$tpl['TREE.protected_method?blank'] =
"<h3>Protected methods</h3>n" .
"<p>This class has no protected methods defined.</p>n";
$tpl['TREE.protected_method:frame'] = "{TREE.protected_method:any}";
$tpl['TREE.protected_method:any'] =
" <dt>{PROTECTED_METHOD_URL} -- {PROTECTED_METHOD.description.short}</dt>n";
$tpl['PROTECTED_METHOD_URL'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?class={TREE.main.name}&method={PROTECTED_METHOD}" .
"&view={VIEW}" class="methodurl">{PROTECTED_METHOD}</a>";
// Properties
$tpl['TREE.property?not_blank'] =
"{TREE.public_property?not_blank}" .
"{TREE.private_property?not_blank}" .
"{TREE.protected_property?not_blank}";
// Public properties
$tpl['TREE.public_property?not_blank'] =
"<h3>Public properties</h3>n" .
"<dl>n" .
"{TREE.public_property}" .
"</dl>n";
$tpl['TREE.public_property?blank'] =
"<h3>Public properties</h3>n" .
"<p>This class has no public properties defined.</p>n";
$tpl['TREE.public_property:frame'] = "{TREE.public_property:any}";
$tpl['TREE.public_property:any'] =
" <dt>{PUBLIC_PROPERTY_URL} -- {PUBLIC_PROPERTY.description.short}</dt>n";
$tpl['PUBLIC_PROPERTY_URL'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?class={TREE.main.name}&property={PUBLIC_PROPERTY}" .
"&view={VIEW}" class="propertyurl">{PUBLIC_PROPERTY}</a>";
// -- for "public" view
$tpl['TREE.public_property#public?not_blank'] =
"<h2>Properties</h2>n" .
"<dl>n" .
"{TREE.public_property}" .
"</dl>n";
// Private properties
$tpl['TREE.private_property?not_blank'] =
"<h3>Private properties</h3>n" .
"<dl>n" .
"{TREE.private_property}" .
"</dl>n";
$tpl['TREE.private_property?blank'] =
"<h3>Private properties</h3>n" .
"<p>This class has no private properties defined.</p>n";
$tpl['TREE.private_property:frame'] = "{TREE.private_property:any}";
$tpl['TREE.private_property:any'] =
" <dt>{PRIVATE_PROPERTY_URL} -- {PRIVATE_PROPERTY.description.short}</dt>n";
$tpl['PRIVATE_PROPERTY_URL'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?class={TREE.main.name}&property={PRIVATE_PROPERTY}" .
"&view={VIEW}" class="propertyurl">{PRIVATE_PROPERTY}</a>";
// Protected properties
$tpl['TREE.protected_property?not_blank'] =
"<h3>Protected properties</h3>n" .
"<dl>n" .
"{TREE.protected_property}" .
"</dl>n";
$tpl['TREE.protected_property?blank'] =
"<h3>Protected properties</h3>n" .
"<p>This class has no protected properties defined.</p>n";
$tpl['TREE.protected_property:frame'] = "{TREE.protected_property:any}";
$tpl['TREE.protected_property:any'] =
" <dt>{PROTECTED_PROPERTY_URL} -- {PROTECTED_PROPERTY.description.short}</dt>n";
$tpl['PROTECTED_PROPERTY_URL'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?class={TREE.main.name}&property={PROTECTED_PROPERTY}" .
"&view={VIEW}" class="propertyurl">{PROTECTED_PROPERTY}</a>";
// Constants and constant groups
$tpl['TREE.main.constants?not_empty'] =
"<h2>Constants</h2>n" .
"<dl>n" .
"{TREE.constant?not_blank}" .
"{TREE.constant_group?not_blank}" .
"</dl>n" .
"{CONSTANTS_URL}";
// Constants
$tpl['TREE.constant?not_blank'] = "{TREE.constant}";
$tpl['TREE.constant:frame'] = "{TREE.constant:any}";
$tpl['TREE.constant:any'] = " <dt><b class="constant">{CONSTANT}</b> -- {CONSTANT.description.short}</dt>n";
// Constant groups
$tpl['TREE.constant_group?not_blank'] = "{TREE.constant_group}";
$tpl['TREE.constant_group:frame'] = "{TREE.constant_group:any}";
$tpl['TREE.constant_group:any'] =
" <dt><p>{CONSTANT_GROUP.description.short}</p>n" .
" <dl>n" .
"{CONSTANT_GROUP.constant}" .
" </dl>n" .
" </dt>n";
$tpl['CONSTANT_GROUP.constant:frame'] = "{CONSTANT_GROUP.constant:any}";
$tpl['CONSTANT_GROUP.constant:any'] = " <dt><b class="constant">{CONSTANT}</b> -- {CONSTANT.comment}</dt>n";
// Constants URL
$tpl['CONSTANTS_URL'] =
"<p><a href="" . $_SERVER['PHP_SELF'] . "?class={TREE.main.name}&constants" .
"&view={VIEW}" class="constanturl">View constants documentation.</a></p>";
// Overwrite hard-coded elements with custom template elements
foreach ($template as $key => $element) {
$tpl[$key] = $element;
}
// Return the template if requested
if ($flag && MDOC_RETURN_TEMPLATE) {
return $tpl;
}
// Fill template in respect with the view level
if (array_key_exists("VIEW:$view", $tpl)) {
$data["TREE"] = $this->tree;
$scope = "TREE";
$tpl['VIEW'] = $view;
$outh = $this->fetch($tpl["VIEW:$view"], $tpl, $scope, $data);
} else {
trigger_error("requested view <b>"$view"</b> is not defined in template", E_USER_WARNING);
return "";
}
return $outh;
}
/**
* Return the documentation of the current library.
*
* This method builds the documentation page for the library found in the current
* source code file. A native XHTML template is hard-coded to render the page
* in the php.net manual style.
*
* The $template parameter can be used to redefine some custom template elements
* or to redefine the whole template. Thus you can create a template for CHM,
* PDF or XML output asuming you set the template FLAG:smart_display "off".
*
* By default, the documentation is returned rendered, but the MDOC_RETURN_TEMPLATE
* flag can be set to return the template "as is" after customization with the
* elements passed in $template parameter.
*
* To build your own template, see the template technical reference page.
*
* This method implements the following error messages:
* 'ERRMSG:language_not_supported' => library must be coded in PHP
* 'ERRMSG:not_a_library' => method called on a file which is not a library
*
* If not already done, this method builds the documentation internal tree.
*
* @param (string) $view set to 'public' to view only API usage details,
* set to 'author' (default value) to view all details
* @param (array) $template optional custom template hooks
* @param (int) $flag set to MDOC_RETURN_TEMPLATE to get the template associative
* array which may be useful to get the hard-coded template
* elements or to help in building custom elements,
* set to MDOC_RETURN_NORMAL (default value) to get a nice
* document page rendered within native or custom template
* @return (string) the library "formated" documentation page
* (string) an error message if the documentation page can't be built
* (array) the template array if the flag MDOC_RETURN_TEMPLATE is set
*/
function getdoc_library($view = "author", $template = array(), $flag = MDOC_RETURN_NORMAL) {
// Parse file into documentation tree if not done yet
if (empty($this->tree)) $this->parse();
// Ensure working on a valid PHP library
$language = empty($this->tree['main']['language']) ?
"unknown" :
$this->tree['main']['language'];
if ($language != "PHP") {
$err = empty($template['ERRMSG:language_not_supported']) ?
"Current code language ($language) isn't supported." :
$template['ERRMSG:language_not_supported'];
return $err;
}
$type = empty($this->tree['main']['type']) ?
"unknown" :
$this->tree['main']['type'];
if ($type != "library") {
$err = empty($template['ERRMSG:not_a_library']) ?
"Current file isn't coding a library (type is $type)." :
$template['ERRMSG:not_a_library'];
return $err;
}
// Set hard-coded template, author view first
$tpl['VIEW:author'] =
"<h1>{TREE.main.name}</h1>n" .
"<p>Library {TREE.main.name} -- {TREE.main.description.short}</p>n" .
"{TREE.main.info?not_blank}" .
"{TREE.main.info.warning?not_blank}" .
"{TREE.main.description.long?not_blank}" .
"{TREE.main.info.experimental?not_blank}" .
"<h2>Functions</h2>n" .
"{TREE.function?not_blank}" .
"{TREE.main.constants?not_empty}" .
"{TREE.cvs?not_blank}";
// Public view
$tpl['VIEW:public'] =
"<h1>{TREE.main.name}</h1>n" .
"<p>Library {TREE.main.name} -- {TREE.main.description.short}</p>n" .
"{TREE.main.info.warning?not_blank}" .
"{TREE.main.description.long?not_blank}" .
"{TREE.main.info.experimental?not_blank}" .
"<h2>Functions</h2>n" .
"{TREE.function?not_blank}" .
"{TREE.main.constants?not_empty}";
// Long description if not blank (?blank not required, default is "")
$tpl['TREE.main.description.long?not_blank'] =
"<h2>Description</h2>n" .
"<p>{TREE.main.description.long}</p>n";
// Optional CVS keywords (revision log excluded)
$tpl['TREE.cvs?not_blank'] = "{TREE.cvs}";
$tpl['TREE.cvs:frame'] =
"<h2>CVS</h2>n" .
"<p>This source code file has some CVS keywords expanded:</p>n" .
"<table class="cvsinfo">n{TREE.cvs:any}</table>n";
$tpl['TREE.cvs:any'] = "<tr><td>{CVS%Keyword}: </td><td> {CVS%Value}</td></tr>n";
$tpl['TREE.cvs:exclude'] = array('Log');
// Main infos
$tpl['TREE.main.info?not_blank'] = "{TREE.main.info}";
$tpl['TREE.main.info:frame'] =
"<table class="libinfo">n" .
"<tr><td colspan="2">Author informations</td></tr>n" .
"{TREE.main.info:any}" .
"</table>n";
$tpl['TREE.main.info:any'] = "<tr><td>@{INFO%Keyword} </td><td> {INFO%Value}</td></tr>n";
$tpl['TREE.main.info:exclude'] = array("experimental", "warning");
// Warning
$tpl['TREE.main.info.warning?not_blank'] = "<p><b>Warning: {TREE.main.info.warning}</b></p>n";
// Experimental status
$tpl['TREE.main.info.experimental?not_blank'] =
"<table class="warning" border="1" width="100%">n" .
"<tr><td align="center"><b>Warning</b></td></tr>n" .
"<tr><td align="left"><p>This library is <span class="emphasis">" .
"<i class="emphasis">EXPERIMENTAL</i></span>.n" .
"The behaviour of this library, the name of this library, and anythingn" .
"else documented about this library may change without notice in a futuren" .
"release.</p></td></tr>n</table>n";
// Functions
$tpl['TREE.function?not_blank'] = "{TREE.function}";
$tpl['TREE.function?blank'] = "<p>This library has no functions defined.</p>n";
$tpl['TREE.function:frame'] =
"<dl>n" .
"{TREE.function:any}" .
"</dl>n";
$tpl['TREE.function:any'] = " <dt>{FUNCTION_URL} -- {FUNCTION.description.short}</dt>n";
$tpl['FUNCTION_URL'] =
"<a href="" . $_SERVER['PHP_SELF'] . "?lib={TREE.main.info.lib}&function={FUNCTION}" .
"&view={VIEW}" class="functionurl">{FUNCTION}</a>";
// Constants and constant groups
$tpl['TREE.main.constants?not_empty'] =
"<h2>Constants</h2>n" .
"<dl>n" .
"{TREE.constant?not_blank}" .
"{TREE.constant_group?not_blank}" .
"</dl>n" .
"{CONSTANTS_URL}";
// Constants
$tpl['TREE.constant?not_blank'] = "{TREE.constant}";
$tpl['TREE.constant:frame'] = "{TREE.constant:any}";
$tpl['TREE.constant:any'] = " <dt><b class="constant">{CONSTANT}</b> -- {CONSTANT.description.short}</dt>n";
// Constant groups
$tpl['TREE.constant_group?not_blank'] = "{TREE.constant_group}";
$tpl['TREE.constant_group:frame'] = "{TREE.constant_group:any}";
$tpl['TREE.constant_group:any'] =
" <dt><p>{CONSTANT_GROUP.description.short}</p>n" .
" <dl>n" .
"{CONSTANT_GROUP.constant}" .
" </dl>n" .
" </dt>n";
$tpl['CONSTANT_GROUP.constant:frame'] = "{CONSTANT_GROUP.constant:any}";
$tpl['CONSTANT_GROUP.constant:any'] = " <dt><b class="constant">{CONSTANT}</b> -- {CONSTANT.comment}</dt>n";
// Constants URL
$tpl['CONSTANTS_URL'] =
"<p><a href="" . $_SERVER['PHP_SELF'] . "?lib={TREE.main.info.lib}&constants" .
"&view={VIEW}" class="constanturl">View constants documentation.</a></p>";
// Overwrite hard-coded elements with custom template elements
foreach ($template as $key => $element) {
$tpl[$key] = $element;
}
// Return the template if requested
if ($flag && MDOC_RETURN_TEMPLATE) {
return $tpl;
}
// Fill template in respect with the view level
if (array_key_exists("VIEW:$view", $tpl)) {
$data["TREE"] = $this->tree;
$scope = "TREE";
$tpl['VIEW'] = $view;
$outh = $this->fetch($tpl["VIEW:$view"], $tpl, $scope, $data);
} else {
trigger_error("requested view <b>"$view"</b> is not defined in template", E_USER_WARNING);
return "";
}
return $outh;
}
/**
* Return the documentation of all constants.
*
* This method builds the documentation page for all constants declared in the
* current source code file. A native XHTML template is hard-coded to render
* the page in the php.net manual style.
*
* The $template parameter can be used to redefine some custom template elements
* or to redefine the whole template. Thus you can create a template for CHM,
* PDF or XML output asuming you set the template FLAG:smart_display "off".
*
* By default, the documentation is returned rendered, but the MDOC_RETURN_TEMPLATE
* flag can be set to return the template "as is" after customization with the
* elements passed in $template parameter.
*
* To build your own template, see the template technical reference page.
*
* This method implements the following error messages:
* 'ERRMSG:language_not_supported' => class or library must be coded in PHP
*
* If not already done, this method builds the documentation internal tree.
*
* @param (string) $view set to 'public' to view only API usage details,
* set to 'author' (default value) to view all details
* @param (array) $template optional custom template hooks
* @param (int) $flag set to MDOC_RETURN_TEMPLATE to get the template associative
* array which may be useful to get the hard-coded template
* elements or to help in building custom elements,
* set to MDOC_RETURN_NORMAL (default value) to get a nice
* document page rendered within native or custom template
* @return (string) the constants "formated" documentation page
* (string) an error message if the documentation page can't be built
* (array) the template array if the flag MDOC_RETURN_TEMPLATE is set
*/
function getdoc_constants($view = "author", $template = array(), $flag = MDOC_RETURN_NORMAL) {
// Parse file into documentation tree if not done yet
if (empty($this->tree)) $this->parse();
// Ensure working on a valid PHP code with at least one constant
$language = empty($this->tree['main']['language']) ?
"unknown" :
$this->tree['main']['language'];
if ($language != "PHP") {
$err = empty($template['ERRMSG:language_not_supported']) ?
"Current code language ($language) isn't supported." :
$template['ERRMSG:language_not_supported'];
return $err;
}
// Set hard-coded template, author view first
$tpl['VIEW:author'] =
"<h1>Constants of {TREE.main.name}</h1>n" .
"{TREE.main.constants?not_empty}" .
"{TREE.main.constants#values?not_empty}";
// Public view
$tpl['VIEW:public'] =
"<h1>Constants of {TREE.main.name}</h1>n" .
"{TREE.main.constants?not_empty}";
// Constants and constant groups
$tpl['TREE.main.constants?empty'] = "<p>This source file has no constants defined.</p>n";
$tpl['TREE.main.constants?not_empty'] =
"<h2>Constants</h2>n" .
"{TREE.constant?not_blank}" .
"{TREE.constant_group?not_blank}";
// Constants declared single
$tpl['TREE.constant?not_blank'] = "{TREE.constant}";
$tpl['TREE.constant:frame'] = "{TREE.constant:any}";
$tpl['TREE.constant:any'] =
"<p>{CONSTANT.description.short}</p>n" .
"<blockquote>n" .
"{CONSTANT.info.warning?not_blank}" .
"{CONSTANT.info.experimental?not_blank}" .
"<p><b class="constant">{CONSTANT}</b>{CONSTANT.info.type?not_blank}</p>n" .
"{CONSTANT.description.long?not_blank}" .
"<p><a href="" . $_SERVER['PHP_SELF'] . "?{TREE.main.type?=library}&constant={CONSTANT}" .
"&view={VIEW}" class="constanturl">Detailed documentation.</a></p>" .
"</blockquote>n";
// Lib or class URL
$tpl['TREE.main.type?=library'] = "lib={TREE.main.name}";
$tpl['TREE.main.type?!=library'] = "class={TREE.main.name}";
// Elements in CONSTANT scope
$tpl['CONSTANT.description.long?not_blank'] = "<p>{CONSTANT.description.long}</p>n";
$tpl['CONSTANT.info.warning?not_blank'] = "<p><b>Warning: {CONSTANT.info.warning}</b></p>n";
$tpl['CONSTANT.info.experimental?not_blank'] =
"<table class="warning" border="1" width="100%">n" .
"<tr><td align="center"><b>Warning</b></td></tr>n" .
"<tr><td align="left"><p>This constant is <span class="emphasis">" .
"<i class="emphasis">EXPERIMENTAL</i></span>.n" .
"The behaviour of this constant, the name of this constant, and anythingn" .
"else documented about this constant may change without notice in a futuren" .
"release.</p></td></tr>n</table>n";
$tpl['CONSTANT.info.type?not_blank'] = ' ({CONSTANT.info.type})';
// Constants declared in groups
$tpl['TREE.constant_group?not_blank'] = "{TREE.constant_group}";
$tpl['TREE.constant_group:frame'] =
"<dl>n" .
"{TREE.constant_group:any}" .
"</dl>n";
$tpl['TREE.constant_group:any'] =
"<p>{CONSTANT_GROUP.description.short}</p>n" .
"<blockquote>n" .
"{CONSTANT_GROUP.info.warning?not_blank}" .
"{CONSTANT_GROUP.info.experimental?not_blank}" .
"<p>n" .
"{CONSTANT_GROUP.constant}" .
"</p>n" .
"{CONSTANT_GROUP.description.long?not_blank}" .
"<p><a href="" . $_SERVER['PHP_SELF'] . "?{TREE.main.type?=library}" .
"&constant_group={CONSTANT_GROUP}&view={VIEW}" class="constanturl">Detailed documentation.</a></p>" .
"</blockquote>n";
// Elements in CONSTANT_GROUP scope
$tpl['CONSTANT_GROUP.description.long?not_blank'] = "<p>{CONSTANT_GROUP.description.long}</p>n";
$tpl['CONSTANT_GROUP.info.warning?not_blank'] = "<p><b>Warning: {CONSTANT_GROUP.info.warning}</b></p>n";
$tpl['CONSTANT_GROUP.info.experimental?not_blank'] =
"<table class="warning" border="1" width="100%">n" .
"<tr><td align="center"><b>Warning</b></td></tr>n" .
"<tr><td align="left"><p>This group of constant is <span class="emphasis">" .
"<i class="emphasis">EXPERIMENTAL</i></span>.n" .
"The behaviour of these constants, the name of these constants, and anythingn" .
"else documented about these constants may change without notice in a futuren" .
"release.</p></td></tr>n</table>n";
// Constant list in constant groups (scope CONSTANT_GROUP.constant a.k.a. CONSTANT)
$tpl['CONSTANT_GROUP.constant:frame'] = "{CONSTANT_GROUP.constant:any}";
$tpl['CONSTANT_GROUP.constant:any'] = "<b class="constant">{CONSTANT}</b>{CONSTANT.comment?not_blank}<br />n";
$tpl['CONSTANT.comment?not_blank'] = " -- {CONSTANT.comment}";
// Constant values
$tpl['TREE.main.constants#values?not_empty'] =
"<h2>Constant values</h2>n" .
"<table border="0" cellspacing="0" cellpadding="2">n" .
"{TREE.constant#values?not_empty}" .
"{TREE.constant_group#values?not_empty}" .
"</table>n";
$tpl['TREE.constant#values?not_empty'] = "{TREE.constant#values}";
$tpl['TREE.constant_group#values?not_empty'] = "{TREE.constant_group#values}";
$tpl['TREE.constant#values:frame'] = "{TREE.constant#values:any}";
$tpl['TREE.constant#values:any'] =
"<tr>n" .
" <td valign="top"><b class="constant">{CONSTANT}</b></td>n" .
" <td valign="top"> = </td>n" .
" <td style="padding: 2px 0px 8px 8px"><code class="value">{CONSTANT.source.value}</code></td>n" .
"</tr>n";
$tpl['TREE.constant_group#values:frame'] = "{TREE.constant_group#values:any}";
$tpl['TREE.constant_group#values:any'] = "{CONSTANT_GROUP.constant#values}";
$tpl['CONSTANT_GROUP.constant#values:frame'] = "{CONSTANT_GROUP.constant#values:any}";
$tpl['CONSTANT_GROUP.constant#values:any'] =
"<tr>n" .
" <td valign="top"><b class="constant">{CONSTANT}</b></td>n" .
" <td valign="top"> = </td>n" .
" <td style="padding: 2px 0px 8px 8px"><code class="value">{CONSTANT.value}</code></td>n" .
"</tr>n";
// Overwrite hard-coded elements with custom template elements
foreach ($template as $key => $element) {
$tpl[$key] = $element;
}
// Return the template if requested
if ($flag && MDOC_RETURN_TEMPLATE) {
return $tpl;
}
// Fill template in respect with the view level
if (array_key_exists("VIEW:$view", $tpl)) {
$data["TREE"] = $this->tree;
$scope = "TREE";
$tpl['VIEW'] = $view;
$outh = $this->fetch($tpl["VIEW:$view"], $tpl, $scope, $data);
} else {
trigger_error("requested view <b>"$view"</b> is not defined in template", E_USER_WARNING);
return "";
}
return $outh;
}
/**
* Return the documentation of the specified constant.
*
* This method builds the documentation page for the specified constant declared
* in the current source code file. A native XHTML template is hard-coded to render
* the page in the php.net manual style.
*
* The $template parameter can be used to redefine some custom template elements
* or to redefine the whole template. Thus you can create a template for CHM,
* PDF or XML output asuming you set the template FLAG:smart_display "off".
*
* By default, the documentation is returned rendered, but the MDOC_RETURN_TEMPLATE
* flag can be set to return the template "as is" after customization with the
* elements passed in $template parameter.
*
* To build your own template, see the template technical reference page.
*
* This method implements the following error messages:
* 'ERRMSG:language_not_supported' => class or library must be coded in PHP
* 'ERRMSG:constant_not_found' => constant not found in the current class or library
*
* If not already done, this method builds the documentation internal tree.
*
* @param (string) $constant the constant identifier
* @param (string) $view set to 'public' to view only API usage details,
* set to 'author' (default value) to view all details
* @param (array) $template optional custom template hooks
* @param (int) $flag set to MDOC_RETURN_TEMPLATE to get the template associative
* array which may be useful to get the hard-coded template
* elements or to help in building custom elements,
* set to MDOC_RETURN_NORMAL (default value) to get a nice
* document page rendered within native or custom template
* @return (string) the constants "formated" documentation page
* (string) an error message if the documentation page can't be built
* (array) the template array if the flag MDOC_RETURN_TEMPLATE is set
*/
function getdoc_constant($constant, $view = "author", $template = array(), $flag = MDOC_RETURN_NORMAL) {
// Parse file into documentation tree if not done yet
if (empty($this->tree)) $this->parse();
// Ensure working on a valid PHP code
$language = empty($this->tree['main']['language']) ?
"unknown" :
$this->tree['main']['language'];
if ($language != "PHP") {
$err = empty($template['ERRMSG:language_not_supported']) ?
"Current code language ($language) isn't supported." :
$template['ERRMSG:language_not_supported'];
return $err;
}
// Find the constant data in singles
if (array_key_exists($constant, $this->tree['constant'])) {
$scope_data = $this->tree['constant'][$constant];
} else {
$err = empty($template['ERRMSG:constant_not_found']) ?
"Constant $constant not found in this file." :
$template['ERRMSG:constant_not_found'];
return $err;
}
// Set hard-coded template, author view first
$tpl['VIEW:author'] =
"<h1>{CONSTANT}</h1>n" .
"<p>Constant {CONSTANT}{CONSTANT.info.type?not_blank} -- {CONSTANT.description.short}</p>n" .
"{CONSTANT.info?not_blank}" .
"{CONSTANT.info.warning?not_blank}" .
"{CONSTANT.description.long?not_blank}" .
"{CONSTANT.info.experimental?not_blank}" .
"<h2>Value</h2>n" .
"<p><code class="value">{CONSTANT.source.value}</code></p>n" .
"<h2>Source code</h2>n" .
"<p>The constant is implemented at line {CONSTANT.source.line} in source code.</p>n" .
"<table border="0" cellpadding="5" bgcolor="#E0E0E0"><tr><td>n" .
"{CONSTANT.source.code}" .
"n</td></tr></table>n" .
"{CONSTANTS_URL}";
$tpl['VIEW:public'] =
"<h1>{CONSTANT}</h1>n" .
"<p>Constant {CONSTANT}{CONSTANT.info.type?not_blank} -- {CONSTANT.description.short}</p>n" .
"{CONSTANT.info.warning?not_blank}" .
"{CONSTANT.description.long?not_blank}" .
"{CONSTANT.info.experimental?not_blank}" .
"<h2>Value</h2>n" .
"<p><code class="value">{CONSTANT.source.value}</code></p>n" .
"{CONSTANTS_URL}";
// Infos
$tpl['CONSTANT.info?not_blank'] = "{CONSTANT.info}";
$tpl['CONSTANT.info:frame'] =
"<table class="constantinfo">n" .
"<tr><td colspan="2">Author informations</td></tr>n" .
"{CONSTANT.info:any}" .
"</table>n";
$tpl['CONSTANT.info:any'] = "<tr><td>@{INFO%Keyword} </td><td> {INFO%Value}</td></tr>n";
$tpl['CONSTANT.info:exclude'] = array("experimental", "type", "warning");
// Type
$tpl['CONSTANT.info.type?not_blank'] = ' ({CONSTANT.info.type})';
// Description
$tpl['CONSTANT.description.long?not_blank'] =
"<h2>Description</h2>n" .
"<p>{CONSTANT.description.long}</p>n";
// Warning
$tpl['CONSTANT.info.warning?not_blank'] = "<p><b>Warning: {CONSTANT.info.warning}</b></p>n";
// Experimental status
$tpl['CONSTANT.info.experimental?not_blank'] =
"<table class="warning" border="1" width="100%">n" .
"<tr><td align="center"><b>Warning</b></td></tr>n" .
"<tr><td align="left"><p>This constant is <span class="emphasis">" .
"<i class="emphasis">EXPERIMENTAL</i></span>.n" .
"The behaviour of this constant, the name of this constant, and anythingn" .
"else documented about this constant may change without notice in a futuren" .
"release.</p></td></tr>n</table>n";
// Constants URL
$tpl['CONSTANTS_URL'] = "<p><a href="" . $_SERVER['PHP_SELF'] . "?{TREE.main.type?=library}" .
"&constants&view={VIEW}" class="constanturl">View constants documentation.</a></p>";
$tpl['TREE.main.type?=library'] = "lib={TREE.main.name}";
$tpl['TREE.main.type?!=library'] = "class={TREE.main.name}";
// Overwrite hard-coded elements with custom template elements
foreach ($template as $key => $element) {
$tpl[$key] = $element;
}
// Return the template if requested
if ($flag && MDOC_RETURN_TEMPLATE) {
return $tpl;
}
// Fill template in respect with the view level and scope data
if (array_key_exists("VIEW:$view", $tpl)) {
$data["TREE"] = $this->tree;
$data["CONSTANT"] = $scope_data;
$scope = "CONSTANT";
$tpl['CONSTANT'] = $constant;
$tpl['VIEW'] = $view;
$outh = $this->fetch($tpl["VIEW:$view"], $tpl, $scope, $data);
} else {
trigger_error("requested view <b>"$view"</b> is not defined in template", E_USER_WARNING);
return "";
}
return $outh;
}
/**
* Return the documentation of the specified constant group.
*
* This method builds the documentation page for the specified constant group declared
* in the current source code file. A native XHTML template is hard-coded to render
* the page in the php.net manual style.
*
* The $template parameter can be used to redefine some custom template elements
* or to redefine the whole template. Thus you can create a template for CHM,
* PDF or XML output asuming you set the template FLAG:smart_display "off".
*
* By default, the documentation is returned rendered, but the MDOC_RETURN_TEMPLATE
* flag can be set to return the template "as is" after customization with the
* elements passed in $template parameter.
*
* To build your own template, see the template technical reference page.
*
* This method implements the following error messages:
* 'ERRMSG:language_not_supported' => class or library must be coded in PHP
* 'ERRMSG:constant_group_not_found' => constant group not found in the
* current class or library
*
* If not already done, this method builds the documentation internal tree.
*
* @param (string) $group_index the constant group index in the documentation tree,
* starting from 1
* @param (string) $view set to 'public' to view only API usage details,
* set to 'author' (default value) to view all details
* @param (array) $template optional custom template hooks
* @param (int) $flag set to MDOC_RETURN_TEMPLATE to get the template associative
* array which may be useful to get the hard-coded template
* elements or to help in building custom elements,
* set to MDOC_RETURN_NORMAL (default value) to get a nice
* document page rendered within native or custom template
* @return (string) the constant group "formated" documentation page
* (string) an error message if the documentation page can't be built
* (array) the template array if the flag MDOC_RETURN_TEMPLATE is set
*/
function getdoc_constant_group($group_index, $view = "author", $template = array(), $flag = MDOC_RETURN_NORMAL) {
// Parse file into documentation tree if not done yet
if (empty($this->tree)) $this->parse();
// Ensure working on a valid PHP code
$language = empty($this->tree['main']['language']) ?
"unknown" :
$this->tree['main']['language'];
if ($language != "PHP") {
$err = empty($template['ERRMSG:language_not_supported']) ?
"Current code language ($language) isn't supported." :
$template['ERRMSG:language_not_supported'];
return $err;
}
// Found the group in constant groups
if (array_key_exists($group_index, $this->tree['constant_group'])) {
$scope_data = $this->tree['constant_group'][$group_index];
} else {
$err = empty($template['ERRMSG:constant_group_not_found']) ?
"Constant group (index $group_index) not found in this file." :
$template['ERRMSG:constant_group_not_found'];
return $err;
}
// Set hard-coded template, author view first
$tpl['VIEW:author'] =
"<h1>Constant group ({CONSTANT_GROUP}) of {TREE.main.name}</h1>n" .
"<p>{CONSTANT_GROUP.description.short}</p>n" .
"{CONSTANT_GROUP.constant}" .
"{CONSTANT_GROUP.info?not_blank}" .
"{CONSTANT_GROUP.info.warning?not_blank}" .
"{CONSTANT_GROUP.description.long?not_blank}" .
"{CONSTANT_GROUP.info.experimental?not_blank}" .
"<h2>Values</h2>n" .
"{CONSTANT_GROUP.constant#values}" .
"<h2>Source code</h2>n" .
"<p>The constants are implemented at line {CONSTANT_GROUP.source.line} in source code.</p>n" .
"<table border="0" cellpadding="5" bgcolor="#E0E0E0"><tr><td>n" .
"{CONSTANT_GROUP.source.code}" .
"n</td></tr></table>n" .
"{CONSTANTS_URL}";
$tpl['VIEW:public'] =
"<h1>Constant group ({CONSTANT_GROUP}) of {TREE.main.name}</h1>n" .
"<p>{CONSTANT_GROUP.description.short}</p>n" .
"{CONSTANT_GROUP.constant}" .
"{CONSTANT_GROUP.info.warning?not_blank}" .
"{CONSTANT_GROUP.description.long?not_blank}" .
"{CONSTANT_GROUP.info.experimental?not_blank}" .
"<h2>Values</h2>n" .
"{CONSTANT_GROUP.constant#values}" .
"{CONSTANTS_URL}";
// Description
$tpl['CONSTANT_GROUP.description.long?not_blank'] =
"<h2>Description</h2>n" .
"<p>{CONSTANT_GROUP.description.long}</p>n";
// Warning
$tpl['CONSTANT_GROUP.info.warning?not_blank'] = "<p><b>Warning: {CONSTANT_GROUP.info.warning}</b></p>n";
// Experimental status
$tpl['CONSTANT_GROUP.info.experimental?not_blank'] =
"<table class="warning" border="1" width="100%">n" .
"<tr><td align="center"><b>Warning</b></td></tr>n" .
"<tr><td align="left"><p>These constants are <span class="emphasis">" .
"<i class="emphasis">EXPERIMENTAL</i></span>.n" .
"The behaviour of these constants, the names of these constants, and anythingn" .
"else documented about these constants may change without notice in a futuren" .
"release.</p></td></tr>n</table>n";
// Main infos
$tpl['CONSTANT_GROUP.info?not_blank'] = "{CONSTANT_GROUP.info}";
$tpl['CONSTANT_GROUP.info:frame'] =
"<table class="constantinfo">n" .
"<tr><td colspan="2">Author informations</td></tr>n" .
"{CONSTANT_GROUP.info:any}" .
"</table>n";
$tpl['CONSTANT_GROUP.info:any'] = "<tr><td>{INFO%Keyword}: </td><td> {INFO%Value}</td></tr>n";
$tpl['CONSTANT_GROUP.info:exclude'] = array('experimental', 'warning');
// Constants and comments
$tpl['CONSTANT_GROUP.constant:frame'] = "<dl>n{CONSTANT_GROUP.constant:any}</dl>n";
$tpl['CONSTANT_GROUP.constant:any'] = " <dt><b class="constant">{CONSTANT}</b>{CONSTANT.comment?not_blank}</dt>n";
$tpl['CONSTANT.comment?not_blank'] = " -- {CONSTANT.comment}";
// Constant values
$tpl['CONSTANT_GROUP.constant#values:frame'] =
"<table border="0" cellspacing="0" cellpadding="2">n" .
"{CONSTANT_GROUP.constant#values:any}" .
"</table>n";
$tpl['CONSTANT_GROUP.constant#values:any'] =
"<tr>n" .
" <td valign="top"><b class="constant">{CONSTANT}</b></td>n" .
" <td valign="top"> = </td>n" .
" <td style="padding: 2px 0px 8px 8px"><code class="value">{CONSTANT.value}</code></td>n" .
"</tr>n";
// Constants URL
$tpl['CONSTANTS_URL'] = "<p><a href="" . $_SERVER['PHP_SELF'] . "?{TREE.main.type?=library}" .
"&constants&view={VIEW}" class="constanturl">View constants documentation.</a></p>";
$tpl['TREE.main.type?=library'] = "lib={TREE.main.name}";
$tpl['TREE.main.type?!=library'] = "class={TREE.main.name}";
// Overwrite hard-coded elements with custom template elements
foreach ($template as $key => $element) {
$tpl[$key] = $element;
}
// Return the template if requested
if ($flag && MDOC_RETURN_TEMPLATE) {
return $tpl;
}
// Fill template in respect with the view level and scope data
if (array_key_exists("VIEW:$view", $tpl)) {
$data["TREE"] = $this->tree;
$data["CONSTANT_GROUP"] = $scope_data;
$scope = "CONSTANT_GROUP";
$tpl['CONSTANT_GROUP'] = $group_index;
$tpl['VIEW'] = $view;
$outh = $this->fetch($tpl["VIEW:$view"], $tpl, $scope, $data);
} else {
trigger_error("requested view <b>"$view"</b> is not defined in template", E_USER_WARNING);
return "";
}
return $outh;
}
/**
* Return the documentation of the specified function.
*
* This method builds the documentation page for the specified function declared
* in the current source code file. A native XHTML template is hard-coded to render
* the page in the php.net manual style.
*
* The $template parameter can be used to redefine some custom template elements
* or to redefine the whole template. Thus you can create a template for CHM,
* PDF or XML output asuming you set the template FLAG:smart_display "off".
*
* By default, the documentation is returned rendered, but the MDOC_RETURN_TEMPLATE
* flag can be set to return the template "as is" after customization with the
* elements passed in $template parameter.
*
* To build your own template, see the template technical reference page.
*
* This method implements the following error messages:
* 'ERRMSG:language_not_supported' => library must be coded in PHP
* 'ERRMSG:not_a_library' => method called on a file which is not a library
* 'ERRMSG:function_not_found' => function not found in the current library
*
* If not already done, this method builds the documentation internal tree.
*
* @param (string) $function the function identifier
* @param (string) $view set to 'public' to view only API usage details,
* set to 'author' (default value) to view all details
* @param (array) $template optional custom template hooks
* @param (int) $flag set to MDOC_RETURN_TEMPLATE to get the template associative
* array which may be useful to get the hard-coded template
* elements or to help in building custom elements,
* set to MDOC_RETURN_NORMAL (default value) to get a nice
* document page rendered within native or custom template
* @return (string) the function "formated" documentation page
* (string) an error message if the documentation page can't be built
* (array) the template array if the flag MDOC_RETURN_TEMPLATE is set
*/
function getdoc_function($function, $view = "author", $template = array(), $flag = MDOC_RETURN_NORMAL) {
// Parse file into documentation tree if not done yet
if (empty($this->tree)) $this->parse();
// Ensure working on a valid PHP library
$language = empty($this->tree['main']['language']) ?
"unknown" :
$this->tree['main']['language'];
if ($language != "PHP") {
$err = empty($template['ERRMSG:language_not_supported']) ?
"Current code language ($language) isn't supported." :
$template['ERRMSG:language_not_supported'];
return $err;
}
$type = empty($this->tree['main']['type']) ?
"unknown" :
$this->tree['main']['type'];
if ($type != "library") {
$err = empty($template['ERRMSG:not_a_library']) ?
"Current file isn't coding a library (type is $type)." :
$template['ERRMSG:not_a_library'];
return $err;
}
// Find the function
if (array_key_exists($function, $this->tree['function'])) {
$scope_data = $this->tree['function'][$function];
} else {
$err = empty($template['ERRMSG:function_not_found']) ?
"Function $function not found in this file." :
$template['ERRMSG:function_not_found'];
return $err;
}
// Set hard-coded template, author view first
$tpl['VIEW:author'] =
"<h1>{FUNCTION}</h1>n" .
"<p>Function {FUNCTION} -- {FUNCTION.description.short}</p>n" .
"{FUNCTION.info?not_blank}" .
"{FUNCTION.info.warning?not_blank}" .
"<h2>Description</h2>n" .
"<p>{FUNCTION_SYNTAX}</p>n" .
"{FUNCTION.description.long?not_blank}" .
"{FUNCTION.info.experimental?not_blank}" .
"<h2>Parameters</h2>n" .
"{FUNCTION.param?not_blank}" .
"<h2>Return values</h2>n" .
"{FUNCTION.return?not_blank}" .
"<h2>Source code</h2>n" .
"<p>The function is implemented at line {FUNCTION.source.line} in source code.</p>n" .
"<table border="0" cellpadding="5" bgcolor="#E0E0E0"><tr><td>n" .
"{FUNCTION.source.code}" .
"n</td></tr></table>n";
$tpl['VIEW:public'] =
"<h1>{FUNCTION}</h1>n" .
"<p>Function {FUNCTION} -- {FUNCTION.description.short}</p>n" .
"{FUNCTION.info.warning?not_blank}" .
"<h2>Description</h2>n" .
"<p>{FUNCTION.SYNTAX}</p>n" .
"{FUNCTION.description.long?not_blank}" .
"{FUNCTION.info.experimental?not_blank}" .
"<h2>Parameters</h2>n" .
"{FUNCTION.param?not_blank}" .
"<h2>Return values</h2>n" .
"{FUNCTION.return?not_blank}";
// Syntax string
$tpl['FUNCTION_SYNTAX'] = "{FUNCTION.source.return_type} <b class="functionname">{FUNCTION}</b> ( {FUNCTION.source.parameters} )";
// Infos
$tpl['FUNCTION.info?not_blank'] = "{FUNCTION.info}";
$tpl['FUNCTION.info:frame'] =
"<table class="functioninfo">n" .
"<tr><td colspan="2">Author informations</td></tr>n" .
"{FUNCTION.info:any}" .
"</table>n";
$tpl['FUNCTION.info:any'] = "<tr><td>@{INFO%Keyword} </td><td> {INFO%Value}</td></tr>n";
$tpl['FUNCTION.info:exclude'] = array('experimental', 'warning');
// Description
$tpl['FUNCTION.description.long?not_blank'] =
"<p>{FUNCTION.description.long}</p>n";
// Warning
$tpl['FUNCTION.info.warning?not_blank'] = "<p><b>Warning: {FUNCTION.info.warning}</b></p>n";
// Experimental status
$tpl['FUNCTION.info.experimental?not_blank'] =
"<table class="warning" border="1" width="100%">n" .
"<tr><td align="center"><b>Warning</b></td></tr>n" .
"<tr><td align="left"><p>This function is <span class="emphasis">" .
"<i class="emphasis">EXPERIMENTAL</i></span>.n" .
"The behaviour of this function, the name of this function, and anythingn" .
"else documented about this function may change without notice in a futuren" .
"release.</p></td></tr>n</table>n";
// Parameters
$tpl['FUNCTION.param?not_blank'] = "{FUNCTION.param}";
$tpl['FUNCTION.param?blank'] = "<p>This function has no parameters defined.</p>";
$tpl['FUNCTION.param:frame'] =
"<div class="variablelist">n" .
"<dl>n" .
"{FUNCTION.param:any}" .
"</dl>n</div>n";
$tpl['FUNCTION.param:any'] =
" <dt><var class="parameter">{PARAM}</var></dt>n" .
" <dd>{PARAM.description}</dd>n" .
"{PARAM.reference?not_blank}" .
"{PARAM.default?not_blank}";
$tpl['PARAM.default?not_blank'] =
" <dd><p>Default value of <var class="parameter">{PARAM}</var> isn" .
" <b class="expression">{PARAM.default}</b>.</p></dd>n";
$tpl['PARAM.reference?blank'] = "";
$tpl['PARAM.reference?not_blank'] =
" <dd><p>Parameter <var class="parameter">{PARAM}</var> isn" .
" passed by reference.</p></dd>n";
// Return values
$tpl['FUNCTION.return?not_blank'] = "{FUNCTION.return}";
$tpl['FUNCTION.return?blank'] = "<p>This function has no return values defined.</p>";
$tpl['FUNCTION.return:frame'] =
"<div class="variablelist">n" .
"<dl>n" .
"{FUNCTION.return:any}" .
"</dl>n</div>n";
$tpl['FUNCTION.return:any'] =
" <dt><var class="type">{RETURN.type}</var></dt>n" .
" <dd>{RETURN.description}</dd>n";
// Overwrite hard-coded elements with custom template elements
foreach ($template as $key => $element) {
$tpl[$key] = $element;
}
// Return the template if requested
if ($flag && MDOC_RETURN_TEMPLATE) {
return $tpl;
}
// Fill template in respect with the view level and scope data
if (array_key_exists("VIEW:$view", $tpl)) {
$data["TREE"] = $this->tree;
$data["FUNCTION"] = $scope_data;
$scope = "FUNCTION";
$tpl['FUNCTION'] = $function;
$tpl['VIEW'] = $view;
$outh = $this->fetch($tpl["VIEW:$view"], $tpl, $scope, $data);
} else {
trigger_error("requested view <b>"$view"</b> is not defined in template", E_USER_WARNING);
return "";
}
return $outh;
}
/**
* Return the documentation of the specified method.
*
* This method builds the documentation page for the specified method declared
* in the current source code file. A native XHTML template is hard-coded to render
* the page in the php.net manual style.
*
* The $template parameter can be used to redefine some custom template elements
* or to redefine the whole template. Thus you can create a template for CHM,
* PDF or XML output asuming you set the template FLAG:smart_display "off".
*
* By default, the documentation is returned rendered, but the MDOC_RETURN_TEMPLATE
* flag can be set to return the template "as is" after customization with the
* elements passed in $template parameter.
*
* To build your own template, see the template technical reference page.
*
* This method implements the following error messages:
* 'ERRMSG:language_not_supported' => class must be coded in PHP
* 'ERRMSG:not_a_class' => method called on a file which is not a class
* 'ERRMSG:method_not_found' => method not found in the current class
*
* If not already done, this method builds the documentation internal tree.
*
* @param (string) $method the method identifier
* @param (string) $view set to 'public' to view only API usage details,
* set to 'author' (default value) to view all details
* @param (array) $template optional custom template hooks
* @param (int) $flag set to MDOC_RETURN_TEMPLATE to get the template associative
* array which may be useful to get the hard-coded template
* elements or to help in building custom elements,
* set to MDOC_RETURN_NORMAL (default value) to get a nice
* document page rendered within native or custom template
* @return (string) the method "formated" documentation page
* (string) an error message if the documentation page can't be built
* (array) the template array if the flag MDOC_RETURN_TEMPLATE is set
*/
function getdoc_method($method, $view = "author", $template = array(), $flag = MDOC_RETURN_NORMAL) {
// Parse file into documentation tree if not done yet
if (empty($this->tree)) $this->parse();
// Ensure working on a valid PHP class
$language = empty($this->tree['main']['language']) ?
"unknown" :
$this->tree['main']['language'];
if ($language != "PHP") {
$err = empty($template['ERRMSG:language_not_supported']) ?
"Current code language ($language) isn't supported." :
$template['ERRMSG:language_not_supported'];
return $err;
}
$type = empty($this->tree['main']['type']) ?
"unknown" :
$this->tree['main']['type'];
if (!in_array($type, array("class", "abstract_class", "final_class", "interface"))) {
$err = empty($template['ERRMSG:not_a_class']) ?
"Current file isn't coding a class (type is $type)." :
$template['ERRMSG:not_a_class'];
return $err;
}
// Find the method
if (array_key_exists($method, $this->tree['method'])) {
$scope_data = $this->tree['method'][$method];
} else {
$err = empty($template['ERRMSG:method_not_found']) ?
"Method $method not found in this file." :
$template['ERRMSG:method_not_found'];
return $err;
}
// Set hard-coded template, author view first
$tpl['VIEW:author'] =
"<h1>{METHOD}</h1>n" .
"<p>{TREE.main.name}::{METHOD} -- {METHOD.description.short}</p>n" .
"{METHOD.source.member?not_blank}" .
"{METHOD.info?not_blank}" .
"{METHOD.info.warning?not_blank}" .
"<h2>Description</h2>n" .
"<p>{METHOD_SYNTAX}</p>n" .
"{METHOD.description.long?not_blank}" .
"{METHOD.info.experimental?not_blank}" .
"<h2>Parameters</h2>n" .
"{METHOD.param?not_blank}" .
"<h2>Return values</h2>n" .
"{METHOD.return?not_blank}" .
"<h2>Source code</h2>n" .
"<p>The method is implemented at line {METHOD.source.line} in source code.</p>n" .
"<table border="0" cellpadding="5" bgcolor="#E0E0E0"><tr><td>n" .
"{METHOD.source.code}" .
"n</td></tr></table>n";
$tpl['VIEW:public'] =
"<h1>{METHOD}</h1>n" .
"<p>{TREE.main.name}::{METHOD} -- {METHOD.description.short}</p>n" .
"{METHOD.info.warning?not_blank}" .
"<h2>Description</h2>n" .
"<p>{METHOD_SYNTAX}</p>n" .
"{METHOD.description.long?not_blank}" .
"{METHOD.info.experimental?not_blank}" .
"<h2>Parameters</h2>n" .
"{METHOD.param?not_blank}" .
"<h2>Return values</h2>n" .
"{METHOD.retu
|
|
Store
Your email: