From 0fe42335695c210024733bdc1ea0b0491d9d593a Mon Sep 17 00:00:00 2001
From: Hypolite Petovan <mrpetovan@gmail.com>
Date: Sun, 19 Nov 2017 08:41:16 -0500
Subject: [PATCH] Improve documentation with brief key

---
 include/conversation.php | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/include/conversation.php b/include/conversation.php
index 196fb6389c..31ab4eadec 100644
--- a/include/conversation.php
+++ b/include/conversation.php
@@ -1362,11 +1362,14 @@ function status_editor(App $a, $x, $notes_cid = 0, $popup = false) {
 }
 
 /**
- * Returns all the children in the given item list of the given parent. If threading
- * is allowed, does it recursively.
+ * Returns all the children in the given item list of the given parent, recusrsively
+ * or not.
+ *
+ * @brief Returns all the children in the given item list of the given parent
  *
  * @param array $item_list
  * @param array $parent
+ * @param bool $recursive
  * @return type
  */
 function get_item_children(array $item_list, array $parent, $recursive = true)
@@ -1394,7 +1397,7 @@ function get_item_children(array $item_list, array $parent, $recursive = true)
 }
 
 /**
- * Recursively sorts a tree-like item array
+ * @brief Recursively sorts a tree-like item array
  *
  * @param array $items
  * @return array
@@ -1412,7 +1415,7 @@ function sort_item_children(array $items)
 }
 
 /**
- * Recursively add all children items at the top level of a list
+ * @brief Recursively add all children items at the top level of a list
  *
  * @param array $children List of items to append
  * @param array $item_list
@@ -1438,6 +1441,8 @@ function add_children_to_list(array $children, array &$item_list)
  * This process is rendered somewhat more complicated because items can be either
  * replies or likes, and these don't factor at all in the reply count/last reply.
  *
+ * @brief Selectively flattens a tree-like item structure to prevent threading stairs
+ *
  * @param array $parent A tree-like array of items
  * @return array
  */
@@ -1488,6 +1493,8 @@ function smart_flatten_conversation(array $parent)
  * sort the top-level posts either on "created" or "commented", and finally
  * append all the items at the top level (???)
  *
+ * @brief Expands a flat item list into a conversation array for display
+ *
  * @param array  $item_list A list of items belonging to one or more conversations
  * @param string $order     Either on "created" or "commented"
  * @return array
@@ -1548,7 +1555,7 @@ function conv_sort(array $item_list, $order)
 }
 
 /**
- * usort() callback to sort item arrays by the created key
+ * @brief usort() callback to sort item arrays by the created key
  *
  * @param array $a
  * @param array $b
@@ -1560,7 +1567,7 @@ function sort_thr_created(array $a, array $b)
 }
 
 /**
- * usort() callback to reverse sort item arrays by the created key
+ * @brief usort() callback to reverse sort item arrays by the created key
  *
  * @param array $a
  * @param array $b
@@ -1572,7 +1579,7 @@ function sort_thr_created_rev(array $a, array $b)
 }
 
 /**
- * usort() callback to sort item arrays by the commented key
+ * @brief usort() callback to sort item arrays by the commented key
  *
  * @param array $a
  * @param array $b