Merge pull request #751 from dawnbreak/docu

:bulb: Add Doxygen fix for @var member variable documentation.

7 files changed, 135 insertions, 87 deletions

diff --git a/include/channel.php b/include/channel.php
index 0a4c9009a..31dca1ae5 100644
--- a/include/channel.php
+++ b/include/channel.php
@@ -57,8 +57,9 @@ function identity_check_service_class($account_id) {
  * Plugins can set additional policies such as full name requirements, character
  * sets, multi-byte length, etc.
  *
+ * @hooks validate_channelname
+ *   * \e array \b name
  * @param string $name
- *
  * @returns nil return if name is valid, or string describing the error state.
  */
 function validate_channelname($name) {
@@ -69,7 +70,7 @@ function validate_channelname($name) {
 	if (strlen($name) > 255)
 		return t('Name too long');
 
-	$arr = array('name' => $name);
+	$arr = ['name' => $name];
 	call_hooks('validate_channelname', $arr);
 
 	if (x($arr, 'message'))
@@ -463,7 +464,6 @@ function create_identity($arr) {
  *       if true, set this default unconditionally
  *       if $force is false only do this if there is no existing default
  */
-
 function set_default_login_identity($account_id, $channel_id, $force = true) {
 	$r = q("select account_default_channel from account where account_id = %d limit 1",
 		intval($account_id)
@@ -478,12 +478,29 @@ function set_default_login_identity($account_id, $channel_id, $force = true) {
 	}
 }
 
-
+/**
+ * @brief Return an array with default list of sections to export.
+ *
+ * @hooks get_default_export_sections
+ *   * \e array \b sections
+ * @return array with default section names to export
+ */
 function get_default_export_sections() {
-	$sections = [ 'channel', 'connections', 'config', 'apps', 'chatrooms', 'events', 'webpages', 'mail', 'wikis' ];
+	$sections = [
+			'channel',
+			'connections',
+			'config',
+			'apps',
+			'chatrooms',
+			'events',
+			'webpages',
+			'mail',
+			'wikis'
+	];
 
 	$cb = [ 'sections' => $sections ];
 	call_hooks('get_default_export_sections', $cb);
+
 	return $cb['sections'];
 }
 
@@ -493,15 +510,17 @@ function get_default_export_sections() {
  * which would be necessary to create a nomadic identity clone. This includes
  * most channel resources and connection information with the exception of content.
  *
+ * @hooks identity_basic_export
+ *   * \e int \b channel_id
+ *   * \e array \b sections
+ *   * \e array \b data
  * @param int $channel_id
  *     Channel_id to export
- * @param boolean $items
- *     Include channel posts (wall items), default false
- *
+ * @param array $sections (optional)
+ *     Which sections to include in the export, default see get_default_export_sections()
  * @returns array
  *     See function for details
  */
-
 function identity_basic_export($channel_id, $sections = null) {
 
 	/*
@@ -511,16 +530,16 @@ function identity_basic_export($channel_id, $sections = null) {
 	if(! $sections) {
 		$sections = get_default_export_sections();
 	}
-		
+
 	$ret = [];
 
 	// use constants here as otherwise we will have no idea if we can import from a site
 	// with a non-standard platform and version.
 
 	$ret['compatibility'] = [
-		'project' => PLATFORM_NAME, 
-		'version' => STD_VERSION, 
-		'database' => DB_UPDATE_VERSION, 
+		'project' => PLATFORM_NAME,
+		'version' => STD_VERSION,
+		'database' => DB_UPDATE_VERSION,
 		'server_role' => Zotlabs\Lib\System::get_server_role()
 	];
 
@@ -549,8 +568,7 @@ function identity_basic_export($channel_id, $sections = null) {
 		if($r)
 			$ret['profile'] = $r;
 
-
-		$r = q("select mimetype, content, os_storage from photo 
+		$r = q("select mimetype, content, os_storage from photo
 			where imgscale = 4 and photo_usage = %d and uid = %d limit 1",
 			intval(PHOTO_PROFILE),
 			intval($channel_id)
@@ -558,8 +576,8 @@ function identity_basic_export($channel_id, $sections = null) {
 
 		if($r) {
 			$ret['photo'] = [
-				'type' => $r[0]['mimetype'], 
-				'data' => (($r[0]['os_storage']) 
+				'type' => $r[0]['mimetype'],
+				'data' => (($r[0]['os_storage'])
 					? base64url_encode(file_get_contents($r[0]['content'])) : base64url_encode($r[0]['content']))
 			];
 		}
@@ -605,7 +623,6 @@ function identity_basic_export($channel_id, $sections = null) {
 		);
 		if($r)
 			$ret['group_member'] = $r;
-
 	}
 
 	if(in_array('config',$sections)) {
@@ -614,7 +631,7 @@ function identity_basic_export($channel_id, $sections = null) {
 		);
 		if($r)
 			$ret['config'] = $r;
-	
+
 		// All other term types will be included in items, if requested.
 
 		$r = q("select * from term where ttype in (%d,%d) and uid = %d",
@@ -641,7 +658,6 @@ function identity_basic_export($channel_id, $sections = null) {
 
 		if($r)
 			$ret['likes'] = $r;
-
 	}
 
 	if(in_array('apps',$sections)) {
@@ -667,7 +683,6 @@ function identity_basic_export($channel_id, $sections = null) {
 			$ret['chatroom'] = $r;
 	}
 
-
 	if(in_array('events',$sections)) {
 		$r = q("select * from event where uid = %d",
 			intval($channel_id)
@@ -697,7 +712,7 @@ function identity_basic_export($channel_id, $sections = null) {
 					$ret['menu'][] = menu_element($ret['channel'],$m);
 			}
 		}
-		$r = q("select * from item where item_type in ( " 
+		$r = q("select * from item where item_type in ( "
 			. ITEM_TYPE_BLOCK . "," . ITEM_TYPE_PDL . "," . ITEM_TYPE_WEBPAGE . " ) and uid = %d",
 			intval($channel_id)
 		);
@@ -707,7 +722,6 @@ function identity_basic_export($channel_id, $sections = null) {
 			$r = fetch_post_tags($r,true);
 			foreach($r as $rr)
 				$ret['webpages'][] = encode_item($rr,true);
-
 		}
 	}
 
@@ -758,7 +772,7 @@ function identity_basic_export($channel_id, $sections = null) {
 		 * Don't export linked resource items. we'll have to pull those out separately.
 		 */
 
-		$r = q("select * from item where item_wall = 1 and item_deleted = 0 and uid = %d 
+		$r = q("select * from item where item_wall = 1 and item_deleted = 0 and uid = %d
 			and created > %s - INTERVAL %s and resource_type = '' order by created",
 			intval($channel_id),
 			db_utcnow(),
@@ -1394,15 +1408,15 @@ function get_my_address() {
 }
 
 /**
- * @brief
+ * @brief Add visitor's zid to our xchan and attempt authentication.
  *
- * If somebody arrives at our site using a zid, add their xchan to our DB if we don't have it already.
+ * If somebody arrives at our site using a zid, add their xchan to our DB if we
+ * don't have it already.
  * And if they aren't already authenticated here, attempt reverse magic auth.
  *
- *
- * @hooks 'zid_init'
- *      string 'zid' - their zid
- *      string 'url' - the destination url
+ * @hooks zid_init
+ *   * \e string \b zid - their zid
+ *   * \e string \b url - the destination url
  */
 function zid_init() {
 	$tmp_str = get_my_address();
@@ -1431,12 +1445,9 @@ function zid_init() {
 }
 
 /**
- * @brief
- *
- * If somebody arrives at our site using a zat, authenticate them
+ * @brief If somebody arrives at our site using a zat, authenticate them.
  *
  */
-
 function zat_init() {
 	if(local_channel() || remote_channel())
 		return;
@@ -1448,7 +1459,6 @@ function zat_init() {
 		$xchan = atoken_xchan($r[0]);
 		atoken_login($xchan);
 	}
-
 }
 
 
@@ -1481,7 +1491,7 @@ function get_theme_uid() {
 *
 * @param int $size
 *  one of (300, 80, 48)
-* @returns string
+* @returns string with path to profile photo
 */
 function get_default_profile_photo($size = 300) {
 	$scheme = get_config('system','default_profile_photo');
@@ -1974,7 +1984,6 @@ function channel_manual_conv_update($channel_id) {
 		$x = get_config('system','manual_conversation_update', 1);
 
 	return intval($x);
-
 }
 
 
@@ -2143,24 +2152,33 @@ function account_remove($account_id,$local = true,$unset_session=true) {
 
 }
 
-function channel_remove($channel_id, $local = true, $unset_session=false) {
+/**
+ * @brief Removes a channel.
+ *
+ * @hooks channel_remove
+ *   * \e array \b entry from channel tabel for $channel_id
+ * @param int $channel_id
+ * @param boolean $local default true
+ * @param boolean $unset_session default false
+ */
+function channel_remove($channel_id, $local = true, $unset_session = false) {
 
 	if(! $channel_id)
 		return;
 
 	logger('Removing channel: ' . $channel_id);
-	logger('channel_remove: local only: ' . intval($local));
+	logger('local only: ' . intval($local));
 
 	$r = q("select * from channel where channel_id = %d limit 1", intval($channel_id));
 	if(! $r) {
-		logger('channel_remove: channel not found: ' . $channel_id);
+		logger('channel not found: ' . $channel_id);
 		return;
 	}
 
 	$channel = $r[0];
 
-	call_hooks('channel_remove',$r[0]);
-	
+	call_hooks('channel_remove', $r[0]);
+
 	if(! $local) {
 
 		$r = q("update channel set channel_deleted = '%s', channel_removed = 1 where channel_id = %d",
@@ -2173,12 +2191,11 @@ function channel_remove($channel_id, $local = true, $unset_session=false) {
 		);
 
 		logger('deleting hublocs',LOGGER_DEBUG);
-	
+
 		$r = q("update hubloc set hubloc_deleted = 1 where hubloc_hash = '%s'",
 			dbesc($channel['channel_hash'])
 		);
 
-
 		$r = q("update xchan set xchan_deleted = 1 where xchan_hash = '%s'",
 			dbesc($channel['channel_hash'])
 		);
@@ -2211,8 +2228,7 @@ function channel_remove($channel_id, $local = true, $unset_session=false) {
 	q("DELETE FROM profile WHERE uid = %d", intval($channel_id));
 	q("DELETE FROM pconfig WHERE uid = %d", intval($channel_id));
 
-	// @FIXME At this stage we need to remove the file resources located under /store/$nickname
-
+	/// @FIXME At this stage we need to remove the file resources located under /store/$nickname
 
 	q("delete from abook where abook_xchan = '%s' and abook_self = 1 ",
 		dbesc($channel['channel_hash'])
@@ -2263,16 +2279,16 @@ function channel_remove($channel_id, $local = true, $unset_session=false) {
 			dbesc($channel['channel_hash'])
 		);
 	}
-	
+
 	//remove from file system
 	$r = q("select channel_address from channel where channel_id = %d limit 1",
 		intval($channel_id)
 	);
-		
+
 	if($r) {
 		$channel_address = $r[0]['channel_address'] ;
 	}
-	if($channel_address) {	
+	if($channel_address) {
 		$f = 'store/' . $channel_address.'/';
 		logger('delete '. $f);
 		if(is_dir($f)) {
@@ -2286,22 +2302,24 @@ function channel_remove($channel_id, $local = true, $unset_session=false) {
 		App::$session->nuke();
 		goaway(z_root());
 	}
-
 }
 
-/*
- * This checks if a channel is allowed to publish executable code.
- * It is up to the caller to determine if the observer or local_channel 
- * is in fact the resource owner whose channel_id is being checked
+/**
+ * @brief This checks if a channel is allowed to publish executable code.
+ *
+ * It is up to the caller to determine if the observer or local_channel
+ * is in fact the resource owner whose channel_id is being checked.
+ *
+ * @param int $channel_id
+ * @return boolean
  */
-
 function channel_codeallowed($channel_id) {
-
 	if(! intval($channel_id))
 		return false;
 
 	$x = channelx_by_n($channel_id);
 	if(($x) && ($x['channel_pageflags'] & PAGE_ALLOWCODE))
 		return true;
+
 	return false;
 }
diff --git a/include/feedutils.php b/include/feedutils.php
index 06a342a3f..6bb7d103e 100644
--- a/include/feedutils.php
+++ b/include/feedutils.php
@@ -742,7 +742,7 @@ function encode_rel_links($links) {
  * @param $importer
  *   The contact_record (joined to user_record) of the local user who owns this
  *   relationship. It is this person's stuff that is going to be updated.
- * @param array $contact[in,out]
+ * @param[in,out] array $contact
  *   The person who is sending us stuff. If not set, we MAY be processing a "follow" activity
  *   from an external network and MAY create an appropriate contact record. Otherwise, we MUST
  *   have a contact record.
@@ -1232,8 +1232,11 @@ function handle_feed($uid, $abook_id, $url) {
 /**
  * @brief Return a XML tag with author information.
  *
+ * @hooks \b atom_author Possibility to add further tags to returned XML string
+ *   * \e string The created XML tag as a string without closing tag
  * @param string $tag The XML tag to create
- * @param string $name Name of the author
+ * @param string $nick preferred username
+ * @param string $name displayed name of the author
  * @param string $uri
  * @param int $h image height
  * @param int $w image width
diff --git a/include/import.php b/include/import.php
index 224bb1803..3b5ddd1f1 100644
--- a/include/import.php
+++ b/include/import.php
@@ -181,7 +181,7 @@ function import_profiles($channel, $profiles) {
  * @param array $channel
  * @param array $hublocs
  * @param unknown $seize
- * @param boolean $moving
+ * @param boolean $moving (optional) default false
  */
 function import_hublocs($channel, $hublocs, $seize, $moving = false) {
 
@@ -585,7 +585,7 @@ function sync_chatrooms($channel, $chatrooms) {
  *
  * @param array $channel where to import to
  * @param array $items
- * @param boolean $sync
+ * @param boolean $sync default false
  * @param array $relocate default null
  */
 function import_items($channel, $items, $sync = false, $relocate = null) {
@@ -654,9 +654,13 @@ function sync_items($channel, $items, $relocate = null) {
 	import_items($channel, $items, true, $relocate);
 }
 
-
-
-function import_item_ids($channel,$itemids) {
+/**
+ * @brief
+ *
+ * @param array $channel A channel array.
+ * @param array $itemids
+ */
+function import_item_ids($channel, $itemids) {
 	if($channel && $itemids) {
 		foreach($itemids as $i) {
 			$r = q("select id from item where mid = '%s' and uid = %d limit 1",
@@ -979,6 +983,7 @@ function import_conv($channel,$convs) {
  *
  * @param array $channel
  * @param array $mails
+ * @param boolean $sync (optional) default false
  */
 function import_mail($channel, $mails, $sync = false) {
 	if($channel && $mails) {
@@ -1276,7 +1281,7 @@ function sync_files($channel, $files) {
  *
  * Replaces $old key with $new key in $arr.
  *
- * @param array[in,out] $arr The array where to work on
+ * @param[in,out] array &$arr The array where to work on
  * @param string $old The old key in the array
  * @param string $new The new key in the array
  */
@@ -1444,7 +1449,7 @@ function import_webpage_element($element, $channel, $type) {
 	// The author is either the owner or whomever was specified
 	$arr['author_xchan'] = (($element['author_xchan']) ? $element['author_xchan'] : get_observer_hash());
 	// Import mimetype if it is a valid mimetype for the element
-	$mimetypes = [	
+	$mimetypes = [
 		'text/bbcode',
 		'text/html',
 		'text/markdown',
diff --git a/include/items.php b/include/items.php
index ffb02a8f0..328079b9d 100755
--- a/include/items.php
+++ b/include/items.php
@@ -298,11 +298,13 @@ function add_source_route($iid, $hash) {
  * or other processing is performed.
  *
  * @param array $arr
+ * @param boolean $allow_code (optional) default false
+ * @param boolean $deliver (optional) default true
  * @returns array
  *  * \e boolean \b success true or false
  *  * \e array \b activity the resulting activity if successful
  */
-function post_activity_item($arr,$allow_code = false,$deliver = true) {
+function post_activity_item($arr, $allow_code = false, $deliver = true) {
 
 	$ret = array('success' => false);
 
@@ -348,7 +350,7 @@ function post_activity_item($arr,$allow_code = false,$deliver = true) {
 	if(($is_comment) && ($arr['obj_type'] === ACTIVITY_OBJ_NOTE))
 		$arr['obj_type'] = ACTIVITY_OBJ_COMMENT;
 
-	if(! ( array_key_exists('allow_cid',$arr) || array_key_exists('allow_gid',$arr) 
+	if(! ( array_key_exists('allow_cid',$arr) || array_key_exists('allow_gid',$arr)
 		|| array_key_exists('deny_cid',$arr) || array_key_exists('deny_gid',$arr))) {
 		$arr['allow_cid']    = $channel['channel_allow_cid'];
 		$arr['allow_gid']    = $channel['channel_allow_gid'];
@@ -648,11 +650,11 @@ function get_item_elements($x,$allow_code = false) {
 		}
 	}
 
-	// Check signature on the body text received. 
+	// Check signature on the body text received.
 	// This presents an issue that we aren't verifying the text that is actually displayed
 	// on this site. We are however verifying the received text was exactly as received.
 	// We have every right to strip content that poses a security risk. You are welcome to
-	// create a plugin to verify the content after filtering if this offends you.  
+	// create a plugin to verify the content after filtering if this offends you.
 
 	if($arr['sig']) {
 
@@ -675,7 +677,7 @@ function get_item_elements($x,$allow_code = false) {
 
 				// If we don't have a public key, strip the signature so it won't show as invalid.
 				// This won't happen in normal use, but could happen if import_author_xchan()
-				// failed to load the zot-info packet due to a server failure and had 
+				// failed to load the zot-info packet due to a server failure and had
 				// to create an alternate xchan with network 'unknown'
 
 				unset($arr['sig']);
@@ -1518,7 +1520,7 @@ function item_store($arr, $allow_exec = false, $deliver = true) {
 	if(array_key_exists('cancel',$arr) && $arr['cancel']) {
 		logger('cancelled by plugin');
 		return $ret;
-	}		
+	}
 
 	if(! $arr['uid']) {
 		logger('item_store: no uid');
@@ -1843,7 +1845,7 @@ logger('revision: ' . $arr['revision']);
 	);
 
 	if($r) {
-		// This will gives us a fresh copy of what's now in the DB and undo the db escaping, 
+		// This will gives us a fresh copy of what's now in the DB and undo the db escaping,
 		// which really messes up the notifications
 
 		$current_post = $r[0]['id'];
@@ -1906,7 +1908,7 @@ logger('revision: ' . $arr['revision']);
 
 	// update the commented timestamp on the parent - unless this is potentially a clone of an older item
 	// which we don't wish to bring to the surface. As the queue only holds deliveries for 3 days, it's
-	// suspected of being an older cloned item if the creation time is older than that. 
+	// suspected of being an older cloned item if the creation time is older than that.
 
 	if($arr['created'] > datetime_convert('','','now - 4 days')) {
 		$z = q("select max(created) as commented from item where parent_mid = '%s' and uid = %d and item_delayed = 0 ",
@@ -1952,7 +1954,7 @@ function item_store_update($arr,$allow_exec = false, $deliver = true) {
 	if(array_key_exists('cancel',$arr) && $arr['cancel']) {
 		logger('cancelled by plugin');
 		return $ret;
-	}		
+	}
 
 	if(! intval($arr['uid'])) {
 		logger('item_store_update: no uid');
@@ -4502,12 +4504,12 @@ function item_create_edit_activity($post) {
 	$new_item['id'] = 0;
 	$new_item['parent'] = 0;
 	$new_item['mid'] = item_message_id();
-	
+
 	$new_item['body'] = sprintf( t('[Edited %s]'), (($update_item['item_thread_top']) ? t('Post','edit_activity') : t('Comment','edit_activity')));
 
 	$new_item['body'] .= "\n\n";
 	$new_item['body'] .= $update_item['body'];
-	
+
 	$new_item['sig'] = '';
 
 	$new_item['verb'] = ACTIVITY_UPDATE;
@@ -4533,10 +4535,10 @@ function item_create_edit_activity($post) {
 				array('rel' => 'photo', 'type' => $item_author['xchan_photo_mimetype'], 'href' => $item_author['xchan_photo_m'])),
 			),
 	));
-	
 
 
-	$x = post_activity_item($new_item);	
+
+	$x = post_activity_item($new_item);
 
 	$post_id = $x['id'];
 	if($post_id) {
@@ -4551,5 +4553,5 @@ function item_create_edit_activity($post) {
 	}
 
 	\Zotlabs\Daemon\Master::Summon(array('Notifier', 'edit_activity', $post_id));
-	
+
 }
diff --git a/include/text.php b/include/text.php
index 46509aabf..162d7c365 100644
--- a/include/text.php
+++ b/include/text.php
@@ -774,9 +774,9 @@ function activity_match($haystack,$needle) {
 }
 
 /**
- * @brief Pull out all #hashtags and @person tags from $s.
+ * @brief Pull out all \#hashtags and \@person tags from $s.
  *
- * We also get @person@domain.com - which would make
+ * We also get \@person\@domain.com - which would make
  * the regex quite complicated as tags can also
  * end a sentence. So we'll run through our results
  * and strip the period from any tags which end with one.
@@ -2079,7 +2079,7 @@ function ids_to_querystr($arr,$idx = 'id',$quote = false) {
  * If $abook is true also include the abook info. This is needed in the API to
  * save extra per item lookups there.
  *
- * @param array[in,out] &$items
+ * @param[in,out] array &$items
  * @param boolean $abook If true also include the abook info
  * @param number $effective_uid
  */
@@ -2175,10 +2175,10 @@ function magic_link($s) {
 }
 
 /**
- * if $escape is true, dbesc() each element before adding quotes
+ * @brief If $escape is true, dbesc() each element before adding quotes.
  *
- * @param array[in,out] &$arr
- * @param boolean $escape default false
+ * @param[in,out] array &$arr
+ * @param boolean $escape (optional) default false
  */
 function stringify_array_elms(&$arr, $escape = false) {
 	for($x = 0; $x < count($arr); $x ++)
@@ -2189,7 +2189,6 @@ function stringify_array_elms(&$arr, $escape = false) {
  * @brief Indents a flat JSON string to make it more human-readable.
  *
  * @param string $json The original JSON string to process.
- *
  * @return string Indented version of the original JSON string.
  */
 function jindent($json) {
@@ -3140,4 +3139,4 @@ function ellipsify($s,$maxlen) {
 		return $s;
 
 	return mb_substr($s,0,$maxlen / 2) . '...' . mb_substr($s,mb_strlen($s) - ($maxlen / 2));
-} 
+}
diff --git a/util/Doxyfile b/util/Doxyfile
index 1bca6cbd4..7be774a81 100644
--- a/util/Doxyfile
+++ b/util/Doxyfile
@@ -32,3 +32,6 @@ DOT_IMAGE_FORMAT = svg
 INTERACTIVE_SVG = YES
 CLASS_GRAPH = YES
 COLLABORATION_GRAPH = NO
+# fix @var (https://bugzilla.gnome.org/show_bug.cgi?id=626105)
+#INPUT_FILTER = "sed -e 's/@var\s/@see /'"
+INPUT_FILTER = "php util/Doxygen_phpvarfilter.php"
diff --git a/util/Doxygen_phpvarfilter.php b/util/Doxygen_phpvarfilter.php
new file mode 100644
index 000000000..da6cf1666
--- /dev/null
+++ b/util/Doxygen_phpvarfilter.php
@@ -0,0 +1,18 @@
+<?php
+/**
+ * @file Doxygen_phpvarfilter.php
+ * @brief A Doxygen INPUT_FILTER to parse \@var member variable documentation.
+ *
+ * An input filter for Doxygen to parse \@var class member variable documentation,
+ * so it is a bit more compatible how anybody else interpretes it.
+ *
+ * @see http://stackoverflow.com/questions/4325224/doxygen-how-to-describe-class-member-variables-in-php/8472180#8472180
+ */
+
+$source = file_get_contents($argv[1]);
+
+$regexp = '#\@var\s+([^\s]+)([^/]+)/\s+(var|public|protected|private)\s+(\$[^\s;=]+)#';
+$replac = '${2} */ ${3} ${1} ${4}';
+$source = preg_replace($regexp, $replac, $source);
+
+echo $source;