From 2844947f5c284748ff30012fbc4caecb2c59c794 Mon Sep 17 00:00:00 2001
From: rabuzarus <>
Date: Sun, 26 Nov 2017 04:33:21 +0100
Subject: [PATCH] tag cloud: add doxygen docu

---
 include/tags.php | 60 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 50 insertions(+), 10 deletions(-)

diff --git a/include/tags.php b/include/tags.php
index 01c39d925..6c13b8296 100644
--- a/include/tags.php
+++ b/include/tags.php
@@ -151,7 +151,19 @@ function update_items() {
 	dba::close($messages);
 }
 
-function tagadelic($uid, $count = 0, $owner_id = 0, $flags = 0, $type = TERM_HASHTAG) {
+/**
+ * @brief Get alphabetical sorted array of used tags/terms of an user including
+ * a weighting by frequency of use.
+ * 
+ * @param int $uid      The user ID.
+ * @param int $count    Max number of displayed tags/terms.
+ * @param int $owner_id The contact id of the owner of the tagged items.
+ * @param string $flags Special item flags.
+ * @param int $type     The tag/term type.
+ * 
+ * @return arr          Alphabetical sorted array of used tags of an user.
+ */
+function tagadelic($uid, $count = 0, $owner_id = 0, $flags = '', $type = TERM_HASHTAG) {
 	require_once('include/security.php');
 
 	$item_condition = item_condition();
@@ -186,14 +198,25 @@ function tagadelic($uid, $count = 0, $owner_id = 0, $flags = 0, $type = TERM_HAS
 	return tag_calc($r);
 }
 
-function wtagblock($uid, $count = 0,$owner_id = 0, $flags = 0, $type = TERM_HASHTAG) {
+/**
+ * @brief Construct a tag/term cloud block for an user.
+ * 
+ * @param int $uid      The user ID.
+ * @param int $count    Max number of displayed tags/terms.
+ * @param int $owner_id The contact ID of the owner of the tagged items.
+ * @param string $flags Special item flags.
+ * @param int $type     The tag/term type.
+ * 
+ * @return string       HTML formatted output.
+ */
+function wtagblock($uid, $count = 0,$owner_id = 0, $flags = '', $type = TERM_HASHTAG) {
 	$o = '';
 	$r = tagadelic($uid, $count, $owner_id, $flags, $type);
-	if($r && $owner_id) {
+	if (count($r)) {
 		$contact = dba::select(
 			"contact",
 			array("url"),
-			array("id" => $owner_id),
+			array("id" => $uid),
 			array("limit" => 1)
 		);
 		$url = System::removedBaseUrl($contact['url']);
@@ -216,6 +239,12 @@ function wtagblock($uid, $count = 0,$owner_id = 0, $flags = 0, $type = TERM_HASH
 	return $o;
 }
 
+/**
+ * @brief Calculate weighting of tags according to the frequency of use.
+ * 
+ * @param array $arr Array of tags/terms with tag/term name and total count of use.
+ * @return array     Alphabetical sorted array of used tags/terms of an user.
+ */
 function tag_calc($arr) {
 	$tags = array();
 	$min = 1e9;
@@ -245,23 +274,34 @@ function tag_calc($arr) {
 	return $tags;
 }
 
-function tags_sort($a,$b) {
+/**
+ * @brief Compare function to sort tags/terms alphabetically.
+ * 
+ * @param type $a
+ * @param type $b
+ * 
+ * @return int
+ */
+function tags_sort($a, $b) {
 	if (strtolower($a[0]) == strtolower($b[0])) {
 		return 0;
 	}
-	return((strtolower($a[0]) < strtolower($b[0])) ? -1 : 1);
+	return ((strtolower($a[0]) < strtolower($b[0])) ? -1 : 1);
 }
 
-
-function tagcloud_wall_widget($arr = array()) {
+/**
+ * @brief Insert a tag cloud widget for the present profile.
+ * 
+ * @param int     $limit Max number of displayed tags.
+ * @return string HTML formattat output.
+ */
+function tagcloud_wall_widget($limit = 50) {
 	$a = get_app();
 
 	if(!$a->profile['profile_uid'] || !$a->profile['url']) {
 		return "";
 	}
 
-	$limit = ((array_key_exists('limit', $arr)) ? intval($arr['limit']) : 50);
-
 	if(feature_enabled($a->profile['profile_uid'], 'tagadelic')) {
 		$owner_id = Contact::getIdForURL($a->profile['url']);