From 13e0151cd2569832588cc9a973bcf40d850edd53 Mon Sep 17 00:00:00 2001
From: Klaus Weidenbach <Klaus.Weidenbach@gmx.net>
Date: Fri, 18 Jan 2019 22:17:10 +0100
Subject: Correct and extend Doxygen comments.

Correct some documentation errors for Doxygen and add
more comments.
Document some undefined variables with @FIXME.
---
 include/help.php | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

(limited to 'include/help.php')

diff --git a/include/help.php b/include/help.php
index 61dbc7bb3..e82fa96da 100644
--- a/include/help.php
+++ b/include/help.php
@@ -7,9 +7,10 @@ use \Michelf\MarkdownExtra;
  * @brief
  *
  * @param string $path
- * @return string|unknown
+ * @param string  $suffix (optional) default null
+ * @return string
  */
-function get_help_fullpath($path,$suffix=null) {
+function get_help_fullpath($path, $suffix = null) {
 
         $docroot = (\App::$override_helproot) ? \App::$override_helproot : 'doc/';
         $docroot = (substr($docroot,-1)!='/') ? $docroot .= '/' : $docroot;
@@ -49,8 +50,8 @@ function get_help_fullpath($path,$suffix=null) {
 /**
  * @brief
  *
- * @param string $tocpath
- * @return string|unknown
+ * @param string $tocpath (optional) default false
+ * @return string
  */
 function get_help_content($tocpath = false) {
 
@@ -171,16 +172,20 @@ function preg_callback_help_include($matches) {
 }
 
 /**
- * @brief
+ * @brief Determines help language.
+ *
+ * If the language was specified in the URL, override the language preference
+ * of the browser. Default to English if both of these are absent.
  *
- * @return boolean|array
+ * @return array Associative array with:
+ *  * \e string \b language -  2-letter ISO 639-1 code ("en")
+ *  * \e boolean \b from_url - true if language from URL overrides browser default
  */
 function determine_help_language() {
 	$lang_detect = new Text_LanguageDetect();
 	// Set this mode to recognize language by the short code like "en", "ru", etc.
 	$lang_detect->setNameMode(2);
-	// If the language was specified in the URL, override the language preference
-	// of the browser. Default to English if both of these are absent.
+
 	if($lang_detect->languageExists(argv(1))) {
 		$lang = argv(1);
 		$from_url = true;
@@ -211,10 +216,10 @@ function find_doc_file($s) {
 }
 
 /**
- * @brief
+ * @brief Search in doc files.
  *
- * @param string $s
- * @return number|mixed|unknown|boolean
+ * @param string $s The search string to search for
+ * @return array
  */
 function search_doc_files($s) {
 
@@ -275,7 +280,6 @@ function doc_rank_sort($s1, $s2) {
  *
  * @return string
  */
-
 function load_context_help() {
 
 	$path = App::$cmd;
@@ -305,7 +309,7 @@ function load_context_help() {
  * @brief
  *
  * @param string $s
- * @return void|boolean[]|number[]|string[]|unknown[]
+ * @return void|array
  */
 function store_doc_file($s) {
 
-- 
cgit v1.2.3