Merge pull request #951 from dawnbreak/docu

:bulb: Add source documentation from recent conversations.

2 files changed, 101 insertions, 32 deletions

diff --git a/include/plugin.php b/include/plugin.php
index 379d8e799..95afdaeb5 100755
--- a/include/plugin.php
+++ b/include/plugin.php
@@ -47,7 +47,10 @@ function uninstall_plugin($plugin) {
 }
 
 /**
- * @brief installs an addon.
+ * @brief Installs an addon.
+ *
+ * This function is called once to install the addon (either from the cli or via
+ * the web admin). This will also call load_plugin() once.
  *
  * @param string $plugin name of the addon
  * @return bool
@@ -188,7 +191,9 @@ function visible_plugin_list() {
 
 
 /**
- * @brief registers a hook.
+ * @brief Registers a hook.
+ *
+ * @see ::Zotlabs::Extend::Hook::register()
  *
  * @param string $hook the name of the hook
  * @param string $file the name of the file that hooks into
@@ -219,6 +224,8 @@ function register_hook($hook, $file, $function, $priority = 0) {
 /**
  * @brief unregisters a hook.
  *
+ * @see ::Zotlabs::Extend::Hook::unregister
+ *
  * @param string $hook the name of the hook
  * @param string $file the name of the file that hooks into
  * @param string $function the name of the function that the hook called
diff --git a/include/text.php b/include/text.php
index 107efe0cb..956f42f7d 100644
--- a/include/text.php
+++ b/include/text.php
@@ -24,12 +24,20 @@ define('RANDOM_STRING_TEXT', 0x01 );
  * @return string substituted string
  */
 function replace_macros($s, $r) {
+	$arr = [
+			'template' => $s,
+			'params' => $r
+	];
 
-	$arr = array('template' => $s, 'params' => $r);
+	/**
+	 * @hooks replace_macros
+	 *   * \e string \b template
+	 *   * \e array \b params
+	 */
 	call_hooks('replace_macros', $arr);
 
 	$t = App::template_engine();
-	$output = $t->replace_macros($arr['template'],$arr['params']);
+	$output = $t->replace_macros($arr['template'], $arr['params']);
 
 	return $output;
 }
@@ -301,12 +309,16 @@ function purify_html($s, $allow_position = false) {
 
 
 /**
- * @brief generate a string that's random, but usually pronounceable.
+ * @brief Generate a string that's random, but usually pronounceable.
  *
  * Used to generate initial passwords.
  *
- * @param int $len
- * @return string
+ * @note In order to create "pronounceable" strings some consonant pairs or
+ * letters that does not make a very good word ending are chopped off, so that
+ * the returned string length can be lower than $len.
+ *
+ * @param int $len max length of generated string
+ * @return string Genereated random, but usually pronounceable string
  */
 function autoname($len) {
 
@@ -343,6 +355,7 @@ function autoname($len) {
 	$midcons = array('ck','ct','gn','ld','lf','lm','lt','mb','mm', 'mn','mp',
 				'nd','ng','nk','nt','rn','rp','rt');
 
+	// avoid these consonant pairs at the end of the string
 	$noend = array('bl', 'br', 'cl','cr','dr','fl','fr','gl','gr',
 				'kh', 'kl','kr','mn','pl','pr','rh','tr','qu','wh');
 
@@ -355,7 +368,7 @@ function autoname($len) {
 	$word = '';
 
 	for ($x = 0; $x < $len; $x ++) {
-		$r = mt_rand(0,count($table) - 1);
+		$r = mt_rand(0, count($table) - 1);
 		$word .= $table[$r];
 
 		if ($table == $vowels)
@@ -364,14 +377,15 @@ function autoname($len) {
 			$table = $vowels;
 	}
 
-	$word = substr($word,0,$len);
+	$word = substr($word, 0, $len);
 
 	foreach ($noend as $noe) {
-		if ((strlen($word) > 2) && (substr($word,-2) == $noe)) {
-			$word = substr($word,0,-1);
+		if ((strlen($word) > 2) && (substr($word, -2) == $noe)) {
+			$word = substr($word, 0, -1);
 			break;
 		}
 	}
+	// avoid the letter 'q' as it does not make a very good word ending
 	if (substr($word, -1) == 'q')
 		$word = substr($word, 0, -1);
 
@@ -1094,17 +1108,19 @@ function sslify($s) {
 	return $s;
 }
 
-
+/**
+ * @brief Get an array of poke verbs.
+ *
+ * @return array
+ *  * \e index is present tense verb
+ *  * \e value is array containing past tense verb, translation of present, translation of past
+ */
 function get_poke_verbs() {
-	// index is present tense verb
-	// value is array containing past tense verb, translation of present, translation of past
-
-	if(get_config('system','poke_basic')) {
+	if (get_config('system', 'poke_basic')) {
 		$arr = array(
-			'poke' => array( 'poked', t('poke'), t('poked')),
+			'poke' => array('poked', t('poke'), t('poked')),
 		);
-	}
-	else {
+	} else {
 		$arr = array(
 			'poke' => array( 'poked', t('poke'), t('poked')),
 			'ping' => array( 'pinged', t('ping'), t('pinged')),
@@ -1114,15 +1130,26 @@ function get_poke_verbs() {
 			'rebuff' => array( 'rebuffed', t('rebuff'), t('rebuffed')),
 		);
 
+		/**
+		 * @hooks poke_verbs
+		 *   * \e array associative array with another array as value
+		 */
 		call_hooks('poke_verbs', $arr);
 	}
 
 	return $arr;
 }
 
+/**
+ * @brief Get an array of mood verbs.
+ *
+ * @return array
+ *   * \e index is the verb
+ *   * \e value is the translated verb
+ */
 function get_mood_verbs() {
 
-	$arr = array(
+	$arr = [
 		'happy'      => t('happy'),
 		'sad'        => t('sad'),
 		'mellow'     => t('mellow'),
@@ -1144,9 +1171,14 @@ function get_mood_verbs() {
 		'motivated'  => t('motivated'),
 		'relaxed'    => t('relaxed'),
 		'surprised'  => t('surprised'),
-	);
+	];
 
+	/**
+	 * @hooks mood_verbs
+	 *   * \e array associative array with mood verbs
+	 */
 	call_hooks('mood_verbs', $arr);
+
 	return $arr;
 }
 
@@ -1513,14 +1545,37 @@ function format_filer(&$item) {
 function generate_map($coord) {
 	$coord = trim($coord);
 	$coord = str_replace(array(',','/','  '),array(' ',' ',' '),$coord);
-	$arr = array('lat' => trim(substr($coord,0,strpos($coord,' '))), 'lon' => trim(substr($coord,strpos($coord,' ')+1)), 'html' => '');
-	call_hooks('generate_map',$arr);
+
+	$arr = [
+			'lat' => trim(substr($coord, 0, strpos($coord, ' '))),
+			'lon' => trim(substr($coord, strpos($coord, ' ')+1)),
+			'html' => ''
+	];
+
+	/**
+	 * @hooks generate_map
+	 *   * \e string \b lat
+	 *   * \e string \b lon
+	 *   * \e string \b html the parsed HTML to return
+	 */
+	call_hooks('generate_map', $arr);
+
 	return (($arr['html']) ? $arr['html'] : $coord);
 }
 
 function generate_named_map($location) {
-	$arr = array('location' => $location, 'html' => '');
-	call_hooks('generate_named_map',$arr);
+	$arr = [
+			'location' => $location,
+			'html' => ''
+	];
+
+	/**
+	 * @hooks generate_named_map
+	 *   * \e string \b location
+	 *   * \e string \b html the parsed HTML to return
+	 */
+	call_hooks('generate_named_map', $arr);
+
 	return (($arr['html']) ? $arr['html'] : $location);
 }
 
@@ -1626,13 +1681,11 @@ function prepare_binary($item) {
 }
 
 
-
-
 /**
  * @brief Given a text string, convert from bbcode to html and add smilie icons.
  *
  * @param string $text
- * @param sting $content_type (optional) default text/bbcode
+ * @param string $content_type (optional) default text/bbcode
  * @param boolean $cache (optional) default false
  *
  * @return string
@@ -3033,8 +3086,19 @@ function text_highlight($s, $lang) {
 			$s = jindent($s);
 	}
 
-	$arr = [ 'text' => $s, 'language' => $lang, 'success' => false ];
-	call_hooks('text_highlight',$arr);
+	$arr = [
+			'text' => $s,
+			'language' => $lang,
+			'success' => false
+	];
+
+	/**
+	 * @hooks text_highlight
+	 *   * \e string \b text
+	 *   * \e string \b language
+	 *   * \e boolean \b success default false
+	 */
+	call_hooks('text_highlight', $arr);
 
 	if($arr['success'])
 		$o = $arr['text'];
@@ -3117,7 +3181,6 @@ function share_unshield($m) {
 
 function cleanup_bbcode($body) {
 
-
 	/**
 	 * fix naked links by passing through a callback to see if this is a hubzilla site
 	 * (already known to us) which will get a zrl, otherwise link with url, add bookmark tag to both.
@@ -3155,7 +3218,6 @@ function cleanup_bbcode($body) {
 
 
 	return $body;
-
 }
 
 function gen_link_id($mid) {