fixed doc in javadoc style

dedalozzo · Apr 24, 2015 · 49203db · 49203db
1 parent 06f3692
commit 49203db
Show file tree

Hide file tree

Showing 3 changed files with 94 additions and 44 deletions.
diff --git a/src/Converter/BBCodeConverter.php b/src/Converter/BBCodeConverter.php
@@ -1,19 +1,24 @@
 <?php
 
-//! @file BBCodeConverter.php
-//! @brief This file contains the BBCodeConverter class.
-//! @details
-//! @author Filippo F. Fadda
-
+/**
+ * @file BBCodeConverter.php
+ * @brief This file contains the BBCodeConverter class.
+ * @details
+ * @author Filippo F. Fadda
+ */
 
 namespace Converter;
 
 
-//! @brief A rudimental converter that takes as input a BBCode formatted text and converts it to Markdown.
+/**
+ * @brief A rudimental converter that takes as input a BBCode formatted text and converts it to Markdown.
+ */
 class BBCodeConverter extends Converter {
 
 
-  //! @brief Removes BBCode size.
+  /**
+   * @brief Removes BBCode size.
+   */
   protected function removeSize() {
 
     $this->text = preg_replace_callback('%\[size=\d*\]([\W\D\w\s]*?)\[/size\]%iu',
@@ -28,7 +33,9 @@ function ($matches) {
   }
 
 
-  //! @brief Removes BBCode center.
+  /**
+   * @brief Removes BBCode center.
+   */
   protected function removeCenter() {
 
     $this->text = preg_replace_callback('%\[center\]([\W\D\w\s]*?)\[/center\]%iu',
@@ -43,7 +50,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replaces BBCode bold.
+  /**
+   * @brief Replaces BBCode bold.
+   */
   protected function replaceBold() {
 
     $this->text = preg_replace_callback('%\[b\]([\W\D\w\s]*?)\[/b\]%iu',
@@ -58,7 +67,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replaces BBCode italic.
+  /**
+   * @brief Replaces BBCode italic.
+   */
   protected function replaceItalic() {
 
     $this->text = preg_replace_callback('%\[i\]([\W\D\w\s]*?)\[/i\]%iu',
@@ -73,7 +84,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replaces BBCode underline. Hoedown support underline.
+  /**
+   * @brief Replaces BBCode underline. Hoedown support underline.
+   */
   protected function replaceUnderline() {
 
     $this->text = preg_replace_callback('%\[u\]([\W\D\w\s]*?)\[/u\]%iu',
@@ -88,7 +101,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replaces BBCode strikethrough.
+  /**
+   * @brief Replaces BBCode strikethrough.
+   */
   protected function replaceStrikethrough() {
 
     $this->text = preg_replace_callback('%\[s\]([\W\D\w\s]*?)\[/s\]%iu',
@@ -103,7 +118,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replaces BBCode lists.
+  /**
+   * @brief Replaces BBCode lists.
+   */
   protected function replaceLists() {
 
     $this->text = preg_replace_callback('%\[list(?P<type>=1)?\](?P<items>[\W\D\w\s]*?)\[/list\]%iu',
@@ -145,7 +162,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replaces BBCode urls.
+  /**
+   * @brief Replaces BBCode urls.
+   */
   protected function replaceUrls() {
 
     $this->text = preg_replace_callback('%\[url\s*=\s*("(?:[^"]*")|\A[^\']*\Z|(?:[^\'">\]\s]+))\s*(?:[^]\s]*)\]([\W\D\w\s]*?)\[/url\]%iu',
@@ -163,7 +182,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replaces BBCode images.
+  /**
+   * @brief Replaces BBCode images.
+   */
   protected function replaceImages() {
 
     $this->text = preg_replace_callback('%\[img\s*\]\s*("(?:[^"]*")|\A[^\']*\Z|(?:[^\'">\]\s]+))\s*(?:[^]\s]*)\[/img\]%iu',
@@ -181,8 +202,10 @@ function ($matches) {
   }
 
 
-  //! @brief Replaces BBCode quotes.
-  //! @details Thanks to Casimir et Hippolyte for helping me with this regex.
+  /**
+   * @brief Replaces BBCode quotes.
+   * @details Thanks to Casimir et Hippolyte for helping me with this regex.
+   */
   protected function replaceQuotes() {
     // Removes the inner quotes, leaving just one level.
     $this->text = preg_replace('~\G(?<!^)(?>(\[quote\b[^]]*](?>[^[]++|\[(?!/?quote)|(?1))*\[/quote])|(?<!\[)(?>[^[]++|\[(?!/?quote))+\K)|\[quote\b[^]]*]\K~', '', $this->text);
@@ -200,7 +223,9 @@ function($matches) {
   }
 
 
-  //! @brief Replaces BBCode snippets.
+  /**
+   * @brief Replaces BBCode snippets.
+   */
   protected function replaceSnippets() {
 
     $this->text = preg_replace_callback('%\[code\s*=?(?P<language>\w*)\](?P<snippet>[\W\D\w\s]*?)\[\/code\]%iu',
@@ -246,7 +271,9 @@ function ($matches) {
   }
 
 
-  //! @brief Converts the provided BBCode text to an equivalent Markdown text.
+  /**
+   * @brief Converts the provided BBCode text to an equivalent Markdown text.
+   */
   public function toMarkdown() {
     $this->removeCenter();
     $this->removeSize();

diff --git a/src/Converter/Converter.php b/src/Converter/Converter.php
@@ -1,24 +1,31 @@
 <?php
 
-//! @file Converter.php
-//! @brief This file contains the Converter class.
-//! @details
-//! @author Filippo F. Fadda
+/**
+ * @file Converter.php
+ * @brief This file contains the Converter class.
+ * @details
+ * @author Filippo F. Fadda
+ */
 
 
-//! @brief This namespace contains all the converters.
+/**
+ * @brief This namespace contains all the converters.
+ */
 namespace Converter;
 
-
-//! @brief This is an abstract converter.
+/**
+ * @brief This is an abstract converter.
+ */
 abstract class Converter {
   protected $text;
 
 
-  //! @brief Constructor.
-  //! @param[in] string $text The text to be converted.
-  //! @param[in] string $id You can provide an identifier which is used in case an exception is raised during the
-  //! conversion process.
+  /**
+   * @brief Constructor.
+   * @param[in] string $text The text to be converted.
+   * @param[in] string $id You can provide an identifier which is used in case an exception is raised during the
+   * conversion process.
+   */
   public function __construct($text, $id = "") {
     $this->text = $text;
     $this->id = (string)$id;

diff --git a/src/Converter/HTMLConverter.php b/src/Converter/HTMLConverter.php
@@ -1,22 +1,28 @@
 <?php
 
-//! @file HTMLConverter.php
-//! @brief This file contains the HTMLConverter class.
-//! @details
-//! @author Filippo F. Fadda
+/**
+ * @file HTMLConverter.php
+ * @brief This file contains the HTMLConverter class.
+ * @details
+ * @author Filippo F. Fadda
+ */
 
 
 namespace Converter;
 
-
-//! @brief A rudimental converter that takes as input HTML and replaces tags with related BBCodes.
-//! @detail This converter doesn't touch the HTML inside pre or code tags.
+/**
+ * @brief A rudimental converter that takes as input HTML and replaces tags with related BBCodes.
+ * @details This converter doesn't touch the HTML inside pre or code tags.
+ */
 class HTMLConverter extends Converter {
   protected $snippets = [];
 
 
-  // Let's find all code snippets inside the body. The code can be inside <pre></pre>, <code></code>, or [code][/code]
-  // if you are using BBCode markup language.
+  /**
+   * @brief Finds all code snippets inside the body, replacing them with appropriate markers.
+   * @details The code can be inside `<pre></pre>`, `<code></code>`, or `[code][/code]` in case you are using BBCode
+   * markup language.
+   */
   protected function removeSnippets() {
     $pattern = '%(?P<openpre><pre>)(?P<contentpre>[\W\D\w\s]*?)(?P<closepre></pre>)|(?P<opencode><code>)(?P<contentcode>[\W\D\w\s]*?)(?P<closecode></code>)|(?P<openbbcode>\[code=?\w*\])(?P<contentbbcode>[\W\D\w\s]*?)(?P<closebbcode>\[/code\])%iu';
 
@@ -30,7 +36,9 @@ protected function removeSnippets() {
   }
 
 
-  //! @brief Restores the snippets, converting the HTML tags to BBCode tags.
+  /**
+   * @brief Restores the snippets, converting the HTML tags to BBCode tags.
+   */
   protected function restoreSnippets() {
     $snippetsCount = count($this->snippets[0]);
 
@@ -48,7 +56,9 @@ protected function restoreSnippets() {
   }
 
 
-  //! @brief Replace links.
+  /**
+   * @brief Replace links.
+   */
   protected function replaceLinks() {
 
     $this->text = preg_replace_callback('%<a[^>]+>(.+?)</a>%iu',
@@ -78,7 +88,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replace images.
+  /**
+   * @brief Replace images.
+   */
   protected function replaceImages() {
     $this->text = preg_replace_callback('/<img[^>]+>/iu',
 
@@ -100,7 +112,9 @@ function ($matches) {
   }
 
 
-  //! @brief Replace all other simple tags, even the lists.
+  /**
+   * @brief Replace all other simple tags, even the lists.
+   */
   protected function replaceOtherTags() {
     $this->text = preg_replace_callback('%</?[a-z][a-z0-9]*[^<>]*>%iu',
 
@@ -183,7 +197,9 @@ function ($matches) {
   }
 
 
-  //! @brief Converts the provided HTML text into BBCode.
+  /**
+   * @brief Converts the provided HTML text into BBCode.
+   */
   public function toBBCode() {
     // We don't want any HTML entities.
     $this->text = htmlspecialchars_decode($this->text);