sbrl-github/Pepperminty-Wiki
sbrl-github
/
Pepperminty-Wiki
mirror of https://github.com/sbrl/Pepperminty-Wiki.git
1
0
Fork 0
Code

Rewrite all function comments in the core code.

This commit is contained in:
Starbeamrainbowlabs 2016-03-26 15:55:50 +00:00
parent 8ae0a9b0b6
commit f39ea4e138
2 changed files with 198 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
build/index.php
View File

@ -458,17 +458,17 @@ if($env->is_logged_in)
} }
/////// Login System End /////// /////// Login System End ///////
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////// Functions //////////////////////////////////////// ////////////////////////////////// Functions //////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
/* /**
* @summary Converts a filesize into a human-readable string. * Converts a filesize into a human-readable string.
* @source http://php.net/manual/en/function.filesize.php#106569 * From http://php.net/manual/en/function.filesize.php#106569
* @editor Starbeamrainbowlabs * Edited by Starbeamrainbowlabs.
* * @param number $bytes The number of bytes to convert.
* @param $bytes - The number of bytes to convert. * @param number $decimals The number of decimal places to preserve.
* @param $decimals - The number of decimal places to preserve. * @return string A human-readable filesize.
*/ */
function human_filesize($bytes, $decimals = 2) function human_filesize($bytes, $decimals = 2)
{ {
@ -478,14 +478,13 @@ function human_filesize($bytes, $decimals = 2)
return $result . @$sz[$factor]; return $result . @$sz[$factor];
} }
/* /**
* @summary Calculates the time sincce a particular timestamp and returns a * Calculates the time sincce a particular timestamp and returns a
* human-readable result. * human-readable result.
* @source http://snippets.pro/snippet/137-php-convert-the-timestamp-to-human-readable-format/ * From http://goo.gl/zpgLgq.
* * @param integer $time The timestamp to convert.
* @param $time - The timestamp to convert. * @return string The time since the given timestamp as
* * a human-readable string.
* @returns {string} - The time since the given timestamp pas a human-readable string.
*/ */
function human_time_since($time) function human_time_since($time)
{ {
@ -506,15 +505,13 @@ function human_time_since($time)
} }
} }
/* /**
* @summary A recursive glob() function. * A recursive glob() function.
* * From http://in.php.net/manual/en/function.glob.php#106595
* @param $pattern - The glob pattern to use to find filenames. * @param string $pattern The glob pattern to use to find filenames.
* @param $flags - The glob flags to use when finding filenames. * @param integer $flags The glob flags to use when finding filenames.
* * @return array An array of the filepaths that match the given glob.
* @returns {array} - An array of the filepaths that match the given glob.
*/ */
// From http://in.php.net/manual/en/function.glob.php#106595
function glob_recursive($pattern, $flags = 0) function glob_recursive($pattern, $flags = 0)
{ {
$files = glob($pattern, $flags); $files = glob($pattern, $flags);
@ -528,13 +525,12 @@ function glob_recursive($pattern, $flags = 0)
return $files; return $files;
} }
/* /**
* @summary Gets a list of all the sub pages of the current page. * Gets a list of all the sub pages of the current page.
* * @param object $pageindex The pageindex to use to search.
* @param $pageindex - The pageindex to use to search. * @param string $pagename The name of the page to list the sub pages of.
* @param $pagename - The name of the page to list the sub pages of. * @return object An object containing all the subpages and their
* * respective distances from the given page name in the pageindex tree.
* @returns An objectt containing all the subpages, and their respective distances from the given page name in the pageindex tree.
*/ */
function get_subpages($pageindex, $pagename) function get_subpages($pageindex, $pagename)
{ {
@ -562,11 +558,10 @@ function get_subpages($pageindex, $pagename)
return $result; return $result;
} }
/* /**
* @summary Makes sure that a subpage's parents exist. Note this doesn't check the pagename itself. * Makes sure that a subpage's parents exist.
* * Note this doesn't check the pagename itself.
* @param The pagename to check. * @param The pagename to check.
*
*/ */
function check_subpage_parents($pagename) function check_subpage_parents($pagename)
{ {
@ -596,10 +591,12 @@ function check_subpage_parents($pagename)
check_subpage_parents($parent_pagename); check_subpage_parents($parent_pagename);
} }
/* /**
* @summary makes a path safe * Makes a path safe.
* * Paths may only contain alphanumeric characters, spaces, underscores, and
* @details paths may only contain alphanumeric characters, spaces, underscores, and dashes * dashes.
* @param string $string The string to make safe.
* @return string A safe version of the given string.
*/ */
function makepathsafe($string) function makepathsafe($string)
{ {
@ -608,10 +605,10 @@ function makepathsafe($string)
return $string; return $string;
} }
/* /**
* @summary Hides an email address from bots by adding random html entities. * Hides an email address from bots by adding random html entities.
* * @param string $str The original email address
* @returns The mangled email address. * @return string The mangled email address.
*/ */
function hide_email($str) function hide_email($str)
{ {
@ -631,29 +628,29 @@ function hide_email($str)
return $hidden_email; return $hidden_email;
} }
/* /**
* @summary Checks to see if $haystack starts with $needle. * Checks to see if $haystack starts with $needle.
* * @param string $haystack The string to search.
* @param $haystack {string} The string to search. * @param string $needle The string to search for at the beginning
* @param $needle {string} The string to search for at the beginning of $haystack. * of $haystack.
* * @return boolean Whether $needle can be found at the beginning
* @returns {boolean} Whether $needle can be found at the beginning of $haystack. * of $haystack.
*/ */
function starts_with($haystack, $needle) function starts_with($haystack, $needle)
{ {
$length = strlen($needle); $length = strlen($needle);
return (substr($haystack, 0, $length) === $needle); return (substr($haystack, 0, $length) === $needle);
} }
/** /**
* mb_stripos all occurences * Case-insensitively finds all occurrences of $needle in $haystack. Handles
* from http://www.pontikis.net/tip/?id=16 * UTF-8 characters correctly.
* From http://www.pontikis.net/tip/?id=16, and
* based on http://www.php.net/manual/en/function.strpos.php#87061 * based on http://www.php.net/manual/en/function.strpos.php#87061
* * @param string $haystack The string to search.
* Find all occurrences of a needle in a haystack (case-insensitive, UTF8) * @param string $needle The string to find.
* * @return array || false An array of match indices, or false if
* @param string $haystack * nothing was found.
* @param string $needle
* @return array or false
*/ */
function mb_stripos_all($haystack, $needle) { function mb_stripos_all($haystack, $needle) {
$s = 0; $i = 0; $s = 0; $i = 0;
@ -670,10 +667,13 @@ function mb_stripos_all($haystack, $needle) {
return false; return false;
} }
/**
* Returns the system's mime type mappings, considering the first extension
* listed to be cacnonical.
* @return array An array of mime type mappings.
*/
function system_mime_type_extensions() { function system_mime_type_extensions() {
global $settings; global $settings;
# Returns the system MIME type mapping of MIME types to extensions, as defined in /etc/mime.types (considering the first
# extension listed to be canonical).
$out = array(); $out = array();
$file = fopen($settings->mime_extension_mappings_location, 'r'); $file = fopen($settings->mime_extension_mappings_location, 'r');
while(($line = fgets($file)) !== false) { while(($line = fgets($file)) !== false) {
@ -690,22 +690,23 @@ function system_mime_type_extensions() {
fclose($file); fclose($file);
return $out; return $out;
} }
/**
* Converts a given mime type to it's associated file extension.
* @param string $type The mime type to convert.
* @return string The extension for the given mime type.
*/
function system_mime_type_extension($type) { function system_mime_type_extension($type) {
# Returns the canonical file extension for the MIME type specified, as defined in /etc/mime.types (considering the first
# extension listed to be canonical).
#
# $type - the MIME type
static $exts; static $exts;
if(!isset($exts)) if(!isset($exts))
$exts = system_mime_type_extensions(); $exts = system_mime_type_extensions();
return isset($exts[$type]) ? $exts[$type] : null; return isset($exts[$type]) ? $exts[$type] : null;
} }
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
//////////////////////////// Security and Consistency Measures //////////////////////////// ////////////////////// Security and Consistency Measures //////////////////////
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
/* /*
* Sort out the pageindex. Create it if it doesn't exist, and load + parse it * Sort out the pageindex. Create it if it doesn't exist, and load + parse it
@ -921,12 +922,12 @@ if(makepathsafe($_GET["page"]) !== $_GET["page"])
$env->page = $_GET["page"]; $env->page = $_GET["page"];
$env->action = strtolower($_GET["action"]); $env->action = strtolower($_GET["action"]);
/////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////// HTML fragments ////////////////////////////////////// //////////////////////////////// HTML fragments ////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
class page_renderer class page_renderer
{ {
public static $html_template = "<!DOCTYPE html> public static $html_template = "<!DOCTYPE html>
@ -1084,13 +1085,12 @@ class page_renderer
public static $nav_divider = "<span class='nav-divider inflexible'> | </span>"; public static $nav_divider = "<span class='nav-divider inflexible'> | </span>";
/* /**
* @summary Function to render a navigation bar from an array of links. See * Renders a navigation bar from an array of links. See
* $settings->nav_links for format information. * $settings->nav_links for format information.
* * @param array $nav_links The links to add to the navigation bar.
* @param $nav_links - The links to add to the navigation bar. * @param array $nav_links_extra The extra nav links to add to
* @param $nav_links_extra - The extra nav links to add to the "More..." * the "More..." menu.
* menu.
*/ */
public static function render_navigation_bar($nav_links, $nav_links_extra, $class = "") public static function render_navigation_bar($nav_links, $nav_links_extra, $class = "")
{ {
@ -1246,12 +1246,16 @@ function add_action($action_name, $func)
$actions->$action_name = $func; $actions->$action_name = $func;
} }
// Function to register a new parser.
$parsers = [ $parsers = [
"none" => function() { "none" => function() {
throw new Exception("No parser registered!"); throw new Exception("No parser registered!");
} }
]; ];
/**
* Registers a new parser.
* @param string $name The name of the new parser to register.
* @param function $parser_code The function to register as a new parser.
*/
function add_parser($name, $parser_code) function add_parser($name, $parser_code)
{ {
global $parsers; global $parsers;
@ -1273,9 +1277,13 @@ function parse_page_source($source)
return $parsers[$settings->parser]($source); return $parsers[$settings->parser]($source);
} }
// Function to register a new proprocessor that will be executed just before // Function to
// an edit is saved.
$save_preprocessors = []; $save_preprocessors = [];
/**
* Register a new proprocessor that will be executed just before
* an edit is saved.
* @param function $func The function to register.
*/
function register_save_preprocessor($func) function register_save_preprocessor($func)
{ {
global $save_preprocessors; global $save_preprocessors;
@ -1283,6 +1291,12 @@ function register_save_preprocessor($func)
} }
$help_sections = []; $help_sections = [];
/**
* Adds a new help section to the help page.
* @param string $index The string to index the new section under.
* @param string $title The title to display above the section.
* @param string $content The content to display.
*/
function add_help_section($index, $title, $content) function add_help_section($index, $title, $content)
{ {
global $help_sections; global $help_sections;

184
core.php
View File

@ -84,17 +84,17 @@ if($env->is_logged_in)
} }
/////// Login System End /////// /////// Login System End ///////
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////// Functions //////////////////////////////////////// ////////////////////////////////// Functions //////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
/* /**
* @summary Converts a filesize into a human-readable string. * Converts a filesize into a human-readable string.
* @source http://php.net/manual/en/function.filesize.php#106569 * From http://php.net/manual/en/function.filesize.php#106569
* @editor Starbeamrainbowlabs * Edited by Starbeamrainbowlabs.
* * @param number $bytes The number of bytes to convert.
* @param $bytes - The number of bytes to convert. * @param number $decimals The number of decimal places to preserve.
* @param $decimals - The number of decimal places to preserve. * @return string A human-readable filesize.
*/ */
function human_filesize($bytes, $decimals = 2) function human_filesize($bytes, $decimals = 2)
{ {
@ -104,14 +104,13 @@ function human_filesize($bytes, $decimals = 2)
return $result . @$sz[$factor]; return $result . @$sz[$factor];
} }
/* /**
* @summary Calculates the time sincce a particular timestamp and returns a * Calculates the time sincce a particular timestamp and returns a
* human-readable result. * human-readable result.
* @source http://snippets.pro/snippet/137-php-convert-the-timestamp-to-human-readable-format/ * From http://goo.gl/zpgLgq.
* * @param integer $time The timestamp to convert.
* @param $time - The timestamp to convert. * @return string The time since the given timestamp as
* * a human-readable string.
* @returns {string} - The time since the given timestamp pas a human-readable string.
*/ */
function human_time_since($time) function human_time_since($time)
{ {
@ -132,15 +131,13 @@ function human_time_since($time)
} }
} }
/* /**
* @summary A recursive glob() function. * A recursive glob() function.
* * From http://in.php.net/manual/en/function.glob.php#106595
* @param $pattern - The glob pattern to use to find filenames. * @param string $pattern The glob pattern to use to find filenames.
* @param $flags - The glob flags to use when finding filenames. * @param integer $flags The glob flags to use when finding filenames.
* * @return array An array of the filepaths that match the given glob.
* @returns {array} - An array of the filepaths that match the given glob.
*/ */
// From http://in.php.net/manual/en/function.glob.php#106595
function glob_recursive($pattern, $flags = 0) function glob_recursive($pattern, $flags = 0)
{ {
$files = glob($pattern, $flags); $files = glob($pattern, $flags);
@ -154,13 +151,12 @@ function glob_recursive($pattern, $flags = 0)
return $files; return $files;
} }
/* /**
* @summary Gets a list of all the sub pages of the current page. * Gets a list of all the sub pages of the current page.
* * @param object $pageindex The pageindex to use to search.
* @param $pageindex - The pageindex to use to search. * @param string $pagename The name of the page to list the sub pages of.
* @param $pagename - The name of the page to list the sub pages of. * @return object An object containing all the subpages and their
* * respective distances from the given page name in the pageindex tree.
* @returns An objectt containing all the subpages, and their respective distances from the given page name in the pageindex tree.
*/ */
function get_subpages($pageindex, $pagename) function get_subpages($pageindex, $pagename)
{ {
@ -188,11 +184,10 @@ function get_subpages($pageindex, $pagename)
return $result; return $result;
} }
/* /**
* @summary Makes sure that a subpage's parents exist. Note this doesn't check the pagename itself. * Makes sure that a subpage's parents exist.
* * Note this doesn't check the pagename itself.
* @param The pagename to check. * @param The pagename to check.
*
*/ */
function check_subpage_parents($pagename) function check_subpage_parents($pagename)
{ {
@ -222,10 +217,12 @@ function check_subpage_parents($pagename)
check_subpage_parents($parent_pagename); check_subpage_parents($parent_pagename);
} }
/* /**
* @summary makes a path safe * Makes a path safe.
* * Paths may only contain alphanumeric characters, spaces, underscores, and
* @details paths may only contain alphanumeric characters, spaces, underscores, and dashes * dashes.
* @param string $string The string to make safe.
* @return string A safe version of the given string.
*/ */
function makepathsafe($string) function makepathsafe($string)
{ {
@ -234,10 +231,10 @@ function makepathsafe($string)
return $string; return $string;
} }
/* /**
* @summary Hides an email address from bots by adding random html entities. * Hides an email address from bots by adding random html entities.
* * @param string $str The original email address
* @returns The mangled email address. * @return string The mangled email address.
*/ */
function hide_email($str) function hide_email($str)
{ {
@ -257,29 +254,29 @@ function hide_email($str)
return $hidden_email; return $hidden_email;
} }
/* /**
* @summary Checks to see if $haystack starts with $needle. * Checks to see if $haystack starts with $needle.
* * @param string $haystack The string to search.
* @param $haystack {string} The string to search. * @param string $needle The string to search for at the beginning
* @param $needle {string} The string to search for at the beginning of $haystack. * of $haystack.
* * @return boolean Whether $needle can be found at the beginning
* @returns {boolean} Whether $needle can be found at the beginning of $haystack. * of $haystack.
*/ */
function starts_with($haystack, $needle) function starts_with($haystack, $needle)
{ {
$length = strlen($needle); $length = strlen($needle);
return (substr($haystack, 0, $length) === $needle); return (substr($haystack, 0, $length) === $needle);
} }
/** /**
* mb_stripos all occurences * Case-insensitively finds all occurrences of $needle in $haystack. Handles
* from http://www.pontikis.net/tip/?id=16 * UTF-8 characters correctly.
* From http://www.pontikis.net/tip/?id=16, and
* based on http://www.php.net/manual/en/function.strpos.php#87061 * based on http://www.php.net/manual/en/function.strpos.php#87061
* * @param string $haystack The string to search.
* Find all occurrences of a needle in a haystack (case-insensitive, UTF8) * @param string $needle The string to find.
* * @return array || false An array of match indices, or false if
* @param string $haystack * nothing was found.
* @param string $needle
* @return array or false
*/ */
function mb_stripos_all($haystack, $needle) { function mb_stripos_all($haystack, $needle) {
$s = 0; $i = 0; $s = 0; $i = 0;
@ -296,10 +293,13 @@ function mb_stripos_all($haystack, $needle) {
return false; return false;
} }
/**
* Returns the system's mime type mappings, considering the first extension
* listed to be cacnonical.
* @return array An array of mime type mappings.
*/
function system_mime_type_extensions() { function system_mime_type_extensions() {
global $settings; global $settings;
# Returns the system MIME type mapping of MIME types to extensions, as defined in /etc/mime.types (considering the first
# extension listed to be canonical).
$out = array(); $out = array();
$file = fopen($settings->mime_extension_mappings_location, 'r'); $file = fopen($settings->mime_extension_mappings_location, 'r');
while(($line = fgets($file)) !== false) { while(($line = fgets($file)) !== false) {
@ -316,22 +316,23 @@ function system_mime_type_extensions() {
fclose($file); fclose($file);
return $out; return $out;
} }
/**
* Converts a given mime type to it's associated file extension.
* @param string $type The mime type to convert.
* @return string The extension for the given mime type.
*/
function system_mime_type_extension($type) { function system_mime_type_extension($type) {
# Returns the canonical file extension for the MIME type specified, as defined in /etc/mime.types (considering the first
# extension listed to be canonical).
#
# $type - the MIME type
static $exts; static $exts;
if(!isset($exts)) if(!isset($exts))
$exts = system_mime_type_extensions(); $exts = system_mime_type_extensions();
return isset($exts[$type]) ? $exts[$type] : null; return isset($exts[$type]) ? $exts[$type] : null;
} }
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
//////////////////////////// Security and Consistency Measures //////////////////////////// ////////////////////// Security and Consistency Measures //////////////////////
/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////
/* /*
* Sort out the pageindex. Create it if it doesn't exist, and load + parse it * Sort out the pageindex. Create it if it doesn't exist, and load + parse it
@ -547,12 +548,12 @@ if(makepathsafe($_GET["page"]) !== $_GET["page"])
$env->page = $_GET["page"]; $env->page = $_GET["page"];
$env->action = strtolower($_GET["action"]); $env->action = strtolower($_GET["action"]);
/////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////// HTML fragments ////////////////////////////////////// //////////////////////////////// HTML fragments ////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
class page_renderer class page_renderer
{ {
public static $html_template = "<!DOCTYPE html> public static $html_template = "<!DOCTYPE html>
@ -710,13 +711,12 @@ class page_renderer
public static $nav_divider = "<span class='nav-divider inflexible'> | </span>"; public static $nav_divider = "<span class='nav-divider inflexible'> | </span>";
/* /**
* @summary Function to render a navigation bar from an array of links. See * Renders a navigation bar from an array of links. See
* $settings->nav_links for format information. * $settings->nav_links for format information.
* * @param array $nav_links The links to add to the navigation bar.
* @param $nav_links - The links to add to the navigation bar. * @param array $nav_links_extra The extra nav links to add to
* @param $nav_links_extra - The extra nav links to add to the "More..." * the "More..." menu.
* menu.
*/ */
public static function render_navigation_bar($nav_links, $nav_links_extra, $class = "") public static function render_navigation_bar($nav_links, $nav_links_extra, $class = "")
{ {
@ -872,12 +872,16 @@ function add_action($action_name, $func)
$actions->$action_name = $func; $actions->$action_name = $func;
} }
// Function to register a new parser.
$parsers = [ $parsers = [
"none" => function() { "none" => function() {
throw new Exception("No parser registered!"); throw new Exception("No parser registered!");
} }
]; ];
/**
* Registers a new parser.
* @param string $name The name of the new parser to register.
* @param function $parser_code The function to register as a new parser.
*/
function add_parser($name, $parser_code) function add_parser($name, $parser_code)
{ {
global $parsers; global $parsers;
@ -899,9 +903,13 @@ function parse_page_source($source)
return $parsers[$settings->parser]($source); return $parsers[$settings->parser]($source);
} }
// Function to register a new proprocessor that will be executed just before // Function to
// an edit is saved.
$save_preprocessors = []; $save_preprocessors = [];
/**
* Register a new proprocessor that will be executed just before
* an edit is saved.
* @param function $func The function to register.
*/
function register_save_preprocessor($func) function register_save_preprocessor($func)
{ {
global $save_preprocessors; global $save_preprocessors;
@ -909,6 +917,12 @@ function register_save_preprocessor($func)
} }
$help_sections = []; $help_sections = [];
/**
* Adds a new help section to the help page.
* @param string $index The string to index the new section under.
* @param string $title The title to display above the section.
* @param string $content The content to display.
*/
function add_help_section($index, $title, $content) function add_help_section($index, $title, $content)
{ {
global $help_sections; global $help_sections;