PHP 7.4 type hints; Added DocBlocks.

Mistralys · Mar 30, 2022 · c0b2ee1 · c0b2ee1
1 parent bf89127
commit c0b2ee1
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 81 deletions.
diff --git a/src/DocFile.php b/src/DocFile.php
@@ -10,20 +10,9 @@
 
 class DocFile
 {
-    /**
-     * @var string
-     */
-    private $title;
-
-    /**
-     * @var string
-     */
-    private $path;
-
-    /**
-     * @var string
-     */
-    private $id;
+    private string $title;
+    private string $path;
+    private string $id;
 
     /**
      * @param string $title

diff --git a/src/DocHeader.php b/src/DocHeader.php
@@ -1,47 +1,43 @@
 <?php
+/**
+ * File containing the class {@see \Mistralys\MarkdownViewer\DocHeader}.
+ *
+ * @package MarkdownViewer
+ * @see \Mistralys\MarkdownViewer\DocHeader
+ */
 
 declare(strict_types=1);
 
 namespace Mistralys\MarkdownViewer;
 
 use AppUtils\ConvertHelper;
-
+use AppUtils\OutputBuffering;
+
+/**
+ * Handles a single header in the document, with
+ * information on the anchor to use to jump to it,
+ * among other things.
+ *
+ * @package MarkdownViewer
+ * @author Sebastian Mordziol <s.mordziol@mistralys.eu>
+ */
 class DocHeader
 {
-    /**
-     * @var string
-     */
-    private $title;
-
-    /**
-     * @var int
-     */
-    private $level;
-
-    /**
-     * @var string
-     */
-    private $tag;
-
-    /**
-     * @var string
-     */
-    private $id;
+    private string $title;
+    private int $level;
+    private string $tag;
+    private string $id;
+    private string $anchor;
 
     /**
      * @var DocHeader[]
      */
-    private $headers = array();
+    private array $headers = array();
 
     /**
      * @var array<string,int>
      */
-    private static $anchors = array();
-
-    /**
-     * @var string
-     */
-    private $anchor;
+    private static array $anchors = array();
 
     public function __construct(string $title, int $level, string $matchedTag)
     {
@@ -136,7 +132,7 @@ public function replace(string $subject, DocFile $file) : string
 
     public function render() : string
     {
-        ob_start();
+        OutputBuffering::start();
 
         ?>
             <li>
@@ -145,7 +141,7 @@ public function render() : string
             </li>
         <?php
 
-        return ob_get_clean();
+        return OutputBuffering::get();
     }
 
     private function renderSubheaders() : string
@@ -154,7 +150,7 @@ private function renderSubheaders() : string
             return '';
         }
 
-        ob_start();
+        OutputBuffering::start();
         ?>
             <ul class="nav-level-<?php echo $this->level ?>">
                 <?php
@@ -166,6 +162,6 @@ private function renderSubheaders() : string
             </ul>
         <?php
 
-        return ob_get_clean();
+        return OutputBuffering::get();
     }
 }
diff --git a/src/DocsException.php b/src/DocsException.php
@@ -1,11 +1,23 @@
 <?php
+/**
+ * File containing the class {@see \Mistralys\MarkdownViewer\DocsException}.
+ *
+ * @package MarkdownViewer
+ * @see \Mistralys\MarkdownViewer\DocsException
+ */
 
 declare(strict_types=1);
 
 namespace Mistralys\MarkdownViewer;
 
 use AppUtils\BaseException;
 
+/**
+ * Exception class for any exceptions thrown in the package.
+ *
+ * @package MarkdownViewer
+ * @author Sebastian Mordziol <s.mordziol@mistralys.eu>
+ */
 class DocsException extends BaseException
 {
 

diff --git a/src/DocsManager.php b/src/DocsManager.php
@@ -1,4 +1,10 @@
 <?php
+/**
+ * File containing the class {@see \Mistralys\MarkdownViewer\DocsManager}.
+ *
+ * @package MarkdownViewer
+ * @see \Mistralys\MarkdownViewer\DocsManager
+ */
 
 declare(strict_types=1);
 
@@ -7,15 +13,23 @@
 use AppUtils\FileHelper;
 use AppUtils\FileHelper_Exception;
 
+/**
+ * Handles a collection of documentation files to use
+ * in the viewer. Handles registering and reading the
+ * list of files.
+ *
+ * @package MarkdownViewer
+ * @author Sebastian Mordziol <s.mordziol@mistralys.eu>
+ */
 class DocsManager
 {
-    const ERROR_NO_FIRST_FILE_FOUND = 82101;
-    const ERROR_UNKNOWN_FILE_ID = 82102;
+    public const ERROR_NO_FIRST_FILE_FOUND = 82101;
+    public const ERROR_UNKNOWN_FILE_ID = 82102;
 
     /**
      * @var DocFile[]
      */
-    private $files = array();
+    private array $files = array();
 
     /**
      * Adds a documentation file to the collection.
@@ -122,7 +136,7 @@ public function getFirstFile() : DocFile
 
     public function getFiles() : array
     {
-        usort($this->files, function (DocFile $a, DocFile $b) {
+        usort($this->files, static function (DocFile $a, DocFile $b) : int {
             return strnatcasecmp($a->getTitle(), $b->getTitle());
         });
 

diff --git a/src/DocsViewer.php b/src/DocsViewer.php
@@ -1,42 +1,34 @@
 <?php
+/**
+ * File containing the class {@see \Mistralys\MarkdownViewer\DocsViewer}.
+ *
+ * @package MarkdownViewer
+ * @see \Mistralys\MarkdownViewer\DocsViewer
+ */
 
 declare(strict_types=1);
 
 namespace Mistralys\MarkdownViewer;
 
+use AppUtils\OutputBuffering;use AppUtils\OutputBuffering_Exception;
+
+/**
+ * Renders the documentation viewer UI, using the
+ * list of documents contained in the manager instance.
+ *
+ * @package MarkdownViewer
+ * @author Sebastian Mordziol <s.mordziol@mistralys.eu>
+ */
 class DocsViewer
 {
-    const ERROR_NO_DOCUMENTS_AVAILABLE = 82001;
-
-    /**
-     * @var string
-     */
-    private $title = 'Documentation';
-
-    /**
-     * @var string
-     */
-    private $menuLabel = 'Available documents';
-
-    /**
-     * @var DocsManager
-     */
-    private $docs;
+    public const ERROR_NO_DOCUMENTS_AVAILABLE = 82001;
 
-    /**
-     * @var bool
-     */
-    private $darkMode = false;
-
-    /**
-     * @var string
-     */
-    private $vendorURL;
-
-    /**
-     * @var string
-     */
-    private $packageURL;
+    private string $title = 'Documentation';
+    private string $menuLabel = 'Available documents';
+    private DocsManager $docs;
+    private bool $darkMode = false;
+    private string $vendorURL;
+    private string $packageURL;
 
     /**
      * @param DocsManager $manager
@@ -201,10 +193,11 @@ private function getPackageURL() : string
     /**
      * @param DocHeader[] $headers
      * @return string
+     * @throws OutputBuffering_Exception
      */
     private function renderMenu(array $headers) : string
     {
-        ob_start();
+        OutputBuffering::start();
 
         ?>
         <ul class="nav-level-0">
@@ -217,6 +210,6 @@ private function renderMenu(array $headers) : string
         </ul>
         <?php
 
-        return ob_get_clean();
+        return OutputBuffering::get();
     }
 }