From 1a737be2b408135177a9e94dcffd0f68c0aca90b Mon Sep 17 00:00:00 2001
From: Klaus Weidenbach <Klaus.Weidenbach@gmx.net>
Date: Tue, 5 Sep 2017 00:23:42 +0200
Subject: :bulb: Improving Doxygen documentation.

Fix some Doxygen parsing errors.
Improve hooks documentation.
---
 include/markdown.php | 71 ++++++++++++++++++++++++++++++++++------------------
 1 file changed, 47 insertions(+), 24 deletions(-)

(limited to 'include/markdown.php')

diff --git a/include/markdown.php b/include/markdown.php
index 0464cf71a..865727b20 100644
--- a/include/markdown.php
+++ b/include/markdown.php
@@ -14,27 +14,25 @@ require_once("include/bbcode.php");
 
 
 /**
- * @brief
+ * @brief Convert Markdown to bbcode.
  *
  * We don't want to support a bbcode specific markdown interpreter
  * and the markdown library we have is pretty good, but provides HTML output.
  * So we'll use that to convert to HTML, then convert the HTML back to bbcode,
  * and then clean up a few Diaspora specific constructs.
  *
- * @param string $s
+ * @param string $s The message as Markdown
  * @param boolean $use_zrl default false
- * @return string
+ * @param array $options default empty
+ * @return string The message converted to bbcode
  */
-
 function markdown_to_bb($s, $use_zrl = false, $options = []) {
 
-
 	if(is_array($s)) {
-		btlogger('markdown_to_bb called with array. ' . print_r($s,true), LOGGER_NORMAL, LOG_WARNING);
+		btlogger('markdown_to_bb called with array. ' . print_r($s, true), LOGGER_NORMAL, LOG_WARNING);
 		return '';
 	}
 
-
 	$s = str_replace("&#xD;","\r",$s);
 	$s = str_replace("&#xD;\n&gt;","",$s);
 
@@ -43,9 +41,18 @@ function markdown_to_bb($s, $use_zrl = false, $options = []) {
 	// if empty link text replace with the url
 	$s = preg_replace("/\[\]\((.*?)\)/ism",'[$1]($1)',$s);
 
-	$x = [ 'text' => $s , 'zrl' => $use_zrl, 'options' => $options ];	
-
-	call_hooks('markdown_to_bb_init',$x);
+	$x = [
+			'text' => $s,
+			'zrl' => $use_zrl,
+			'options' => $options
+	];
+	/**
+	 * @hooks markdown_to_bb_init
+	 *   * \e string \b text - The message as Markdown and what will get returned
+	 *   * \e boolean \b zrl
+	 *   * \e array \b options
+	 */
+	call_hooks('markdown_to_bb_init', $x);
 
 	$s = $x['text'];
 
@@ -67,7 +74,7 @@ function markdown_to_bb($s, $use_zrl = false, $options = []) {
 
 	// Convert everything that looks like a link to a link
 	if($use_zrl) {
-		$s = str_replace(array('[img','/img]'),array('[zmg','/zmg]'),$s);
+		$s = str_replace(['[img', '/img]'], ['[zmg', '/zmg]'], $s);
 		$s = preg_replace("/([^\]\=]|^)(https?\:\/\/)([a-zA-Z0-9\:\/\-\?\&\;\.\=\_\~\#\%\$\!\+\,\@\(\)]+)/ism", '$1[zrl=$2$3]$2$3[/zrl]',$s);
 	}
 	else {
@@ -80,13 +87,22 @@ function markdown_to_bb($s, $use_zrl = false, $options = []) {
 	// Don't show link to full picture (until it is fixed)
 	$s = scale_external_images($s, false);
 
-	call_hooks('markdown_to_bb',$s);
+	/**
+	 * @hooks markdown_to_bb
+	 *   * \e string - The already converted message as bbcode
+	 */
+	call_hooks('markdown_to_bb', $s);
 
 	return $s;
 }
 
 
-
+/**
+ * @brief
+ *
+ * @param array $match
+ * @return string
+ */
 function bb_to_markdown_share($match) {
 
 	$matches = array();
@@ -153,17 +169,22 @@ function bb_to_markdown_share($match) {
 }
 
 
-
+/**
+ * @brief Convert bbcode to Markdown.
+ *
+ * @param string $Text The message as bbcode
+ * @param array $options default empty
+ * @return string The message converted to Markdown
+ */
 function bb_to_markdown($Text, $options = []) {
 
 	/*
 	 * Transform #tags, strip off the [url] and replace spaces with underscore
 	 */
 
-	$Text = preg_replace_callback('/#\[([zu])rl\=(.*?)\](.*?)\[\/[(zu)]rl\]/i', 
+	$Text = preg_replace_callback('/#\[([zu])rl\=(.*?)\](.*?)\[\/[(zu)]rl\]/i',
 		create_function('$match', 'return \'#\'. str_replace(\' \', \'_\', $match[3]);'), $Text);
 
-
 	$Text = preg_replace('/#\^\[([zu])rl\=(.*?)\](.*?)\[\/([zu])rl\]/i', '[$1rl=$2]$3[/$4rl]', $Text);
 
 	// Converting images with size parameters to simple images. Markdown doesn't know it.
@@ -173,7 +194,12 @@ function bb_to_markdown($Text, $options = []) {
 
 	$x = [ 'bbcode' => $Text, 'options' => $options ];
 
-	call_hooks('bb_to_markdown_bb',$x);
+	/**
+	 * @hooks bb_to_markdown_bb
+	 *   * \e string \b bbcode - The message as bbcode and what will get returned
+	 *   * \e array \b options
+	 */
+	call_hooks('bb_to_markdown_bb', $x);
 
 	$Text = $x['bbcode'];
 
@@ -202,14 +228,16 @@ function bb_to_markdown($Text, $options = []) {
 
 	$Text = trim($Text);
 
+	/**
+	 * @hooks bb_to_markdown
+	 *   * \e string - The already converted message as bbcode and what will get returned
+	 */
 	call_hooks('bb_to_markdown', $Text);
 
 	return $Text;
-
 }
 
 
-
 /**
  * @brief Convert a HTML text into Markdown.
  *
@@ -217,8 +245,6 @@ function bb_to_markdown($Text, $options = []) {
  *
  * If the HTML text can not get parsed it will return an empty string.
  *
- * @see HTMLToMarkdown
- *
  * @param string $html The HTML code to convert
  * @return string Markdown representation of the given HTML text, empty on error
  */
@@ -232,8 +258,5 @@ function html2markdown($html) {
 		logger("Invalid HTML. HTMLToMarkdown library threw an exception.");
 	}
 
-	// The old html 2 markdown library "pixel418/markdownify": "^2.2",
-	//$md = new HtmlConverter();
-	//$markdown = $md->convert($Text);
 	return $markdown;
 }
-- 
cgit v1.2.3