From a4cadf67ffcb705ab2940a473e46f1fe49737fb4 Mon Sep 17 00:00:00 2001
From: Jordan LeDoux <jordan.ledoux@gmail.com>
Date: Mon, 5 Jul 2021 19:41:43 -0700
Subject: [PATCH] Updated docblocks for Mason v0.2

---
 composer.json                                 |   2 +-
 docs/roster/latest/Samsara/Roster/App.md      |  58 ++++---
 docs/roster/latest/Samsara/Roster/Roster.md   | 144 +++++++++++++-----
 src/Samsara/Roster/App.php                    |  10 +-
 .../Processors/Base/BaseCodeProcessor.php     |   4 +-
 .../MethodArgumentDetailProcessor.php         |   6 +-
 .../Processors/MethodArgumentProcessor.php    |   6 +-
 .../Roster/Processors/MethodProcessor.php     |  15 +-
 .../Roster/Processors/PropertyProcessor.php   |   4 +-
 src/Samsara/Roster/Roster.php                 | 111 +++++++++++++-
 10 files changed, 272 insertions(+), 88 deletions(-)

diff --git a/composer.json b/composer.json
index c8311bc..b82a5ab 100644
--- a/composer.json
+++ b/composer.json
@@ -24,7 +24,7 @@
   "license": "GPL-3.0-only",
   "require": {
     "symfony/console": "^v5.3",
-    "samsara/mason": "^0.1",
+    "samsara/mason": "^0.2",
     "hassankhan/config": "^2.2",
     "symfony/yaml": "^5.3",
     "php": ">=8.0"
diff --git a/docs/roster/latest/Samsara/Roster/App.md b/docs/roster/latest/Samsara/Roster/App.md
index 9d313af..7389316 100644
--- a/docs/roster/latest/Samsara/Roster/App.md
+++ b/docs/roster/latest/Samsara/Roster/App.md
@@ -1,6 +1,8 @@
 # Samsara\Roster > App
 
-*No description available*
+Class App
+
+ This class configures and sets up the Symfony/Console application so that it is ready for the command to be executed.
 
 
 ## Inheritance
@@ -33,7 +35,7 @@
 
 !!! signature constant "App::VERSION"
     value
-    :   'v0.1.0-alpha'
+    :   'v0.1.0'
 
 
 
@@ -99,7 +101,7 @@
     :   string[][]
 
     description
-    :   An array of abbreviations
+    :   *No description available*
 
 Returns an array of possible abbreviations given a set of names.
 
@@ -190,7 +192,7 @@ Returns an array of possible abbreviations given a set of names.
     :   int
 
     description
-    :   0 if everything went fine, or an error code
+    :   *No description available*
 
 Runs the current application.
 
@@ -227,7 +229,7 @@ Runs the current application.
     :   HelperSet
 
     description
-    :   The HelperSet instance associated with this command
+    :   *No description available*
 
 Get the helper set associated with the command.
 
@@ -255,7 +257,7 @@ Get the helper set associated with the command.
     :   InputDefinition
 
     description
-    :   The InputDefinition instance
+    :   *No description available*
 
 Gets the InputDefinition related to this Application.
 
@@ -266,7 +268,7 @@ Gets the InputDefinition related to this Application.
     :   string
 
     description
-    :   A help message
+    :   *No description available*
 
 Gets the help message.
 
@@ -277,7 +279,7 @@ Gets the help message.
     :   bool
 
     description
-    :   Whether to catch exceptions or not during commands execution
+    :   *No description available*
 
 Gets whether to catch exceptions or not during commands execution.
 
@@ -305,7 +307,7 @@ Gets whether to catch exceptions or not during commands execution.
     :   bool
 
     description
-    :   Whether to automatically exit after a command execution or not
+    :   *No description available*
 
 Gets whether to automatically exit after a command execution or not.
 
@@ -333,7 +335,7 @@ Gets whether to automatically exit after a command execution or not.
     :   string
 
     description
-    :   The application name
+    :   *No description available*
 
 Gets the name of the application.
 
@@ -361,7 +363,7 @@ Gets the name of the application.
     :   string
 
     description
-    :   The application version
+    :   *No description available*
 
 Gets the application version.
 
@@ -389,7 +391,7 @@ Gets the application version.
     :   string
 
     description
-    :   The long application version
+    :   *No description available*
 
 Returns the long version of the application.
 
@@ -408,7 +410,7 @@ Returns the long version of the application.
     :   Command
 
     description
-    :   The newly created command
+    :   *No description available*
 
 Registers a new command.
 
@@ -448,7 +450,7 @@ Adds an array of command objects.
     :   Command|null
 
     description
-    :   The registered command if enabled or null
+    :   *No description available*
 
 Adds a command object.
 
@@ -469,9 +471,7 @@ Adds a command object.
     :   Command
 
     description
-    :   A Command object
-
-
+    :   *No description available*
 
 Returns a registered command by name or alias.
 
@@ -490,7 +490,7 @@ Returns a registered command by name or alias.
     :   bool
 
     description
-    :   true if the command exists, false otherwise
+    :   *No description available*
 
 Returns true if the command exists, false otherwise.
 
@@ -501,7 +501,7 @@ Returns true if the command exists, false otherwise.
     :   string[]
 
     description
-    :   An array of namespaces
+    :   *No description available*
 
 Returns an array of all unique namespaces used by currently registered commands.
 
@@ -522,9 +522,7 @@ Returns an array of all unique namespaces used by currently registered commands.
     :   string
 
     description
-    :   A registered namespace
-
-
+    :   *No description available*
 
 Finds a registered namespace by a name or an abbreviation.
 
@@ -543,9 +541,7 @@ Finds a registered namespace by a name or an abbreviation.
     :   Command
 
     description
-    :   A Command instance
-
-
+    :   *No description available*
 
 Finds a command by name or alias.
 
@@ -566,7 +562,7 @@ Finds a command by name or alias.
     :   Command[]
 
     description
-    :   An array of Command instances
+    :   *No description available*
 
 Gets the commands (registered in the given namespace if provided).
 
@@ -620,7 +616,7 @@ Gets the commands (registered in the given namespace if provided).
     :   string
 
     description
-    :   The namespace of the command
+    :   *No description available*
 
 Returns the namespace part of the command name.
 
@@ -743,7 +739,7 @@ Sets the default Command name.
     :   int
 
     description
-    :   0 if everything went fine, or an error code
+    :   *No description available*
 
 Runs the current command.
 
@@ -775,7 +771,7 @@ Gets the name of the command based on input.
     :   InputDefinition
 
     description
-    :   An InputDefinition instance
+    :   *No description available*
 
 Gets the default input definition.
 
@@ -786,7 +782,7 @@ Gets the default input definition.
     :   Command[]
 
     description
-    :   An array of default Command instances
+    :   *No description available*
 
 Gets the default commands that should always be available.
 
@@ -797,7 +793,7 @@ Gets the default commands that should always be available.
     :   HelperSet
 
     description
-    :   A HelperSet instance
+    :   *No description available*
 
 Gets the default helper set with the helpers that should always be available.
 
diff --git a/docs/roster/latest/Samsara/Roster/Roster.md b/docs/roster/latest/Samsara/Roster/Roster.md
index 0c66618..f8f922a 100644
--- a/docs/roster/latest/Samsara/Roster/Roster.md
+++ b/docs/roster/latest/Samsara/Roster/Roster.md
@@ -1,6 +1,10 @@
 # Samsara\Roster > Roster
 
-*No description available*
+Class Roster
+
+ This class performs all of the command logic to actually build the documentation with the right options and in the right order.
+
+ The execute() method is the only one directly invoked by the CLI application, and it dispatches all other function calls.
 
 
 ## Inheritance
@@ -75,16 +79,16 @@
     **return**
 
     type
-    :   *mixed* (assumed)
+    :   void
 
     description
     :   *No description available*
 
-!!! signature "protected Roster->execute(Symfony\Component\Console\Input\InputInterface $input, Symfony\Component\Console\Output\OutputInterface $output)"
+!!! signature "protected Roster->execute(InputInterface $input, OutputInterface $output)"
     **$input**
 
     type
-    :   Symfony\Component\Console\Input\InputInterface
+    :   InputInterface
 
     description
     :   *No description available*
@@ -92,7 +96,7 @@
     **$output**
 
     type
-    :   Symfony\Component\Console\Output\OutputInterface
+    :   OutputInterface
 
     description
     :   *No description available*
@@ -105,6 +109,10 @@
     description
     :   *No description available*
 
+execute() method
+
+ This function performs all of the application logic. All actions performed by the script are at least started from this function.
+
 !!! signature "protected Roster->buildMkdocsNav(string $baseExportPath)"
     **$baseExportPath**
 
@@ -112,16 +120,39 @@
     :   string
 
     description
-    :   *No description available*
+    :   The realpath() of the location docs are exported to
 
     **return**
 
     type
-    :   array|string
+    :   array
 
     description
     :   *No description available*
 
+buildMkdocsNav
+
+ This function takes in the base export path and outputs the namespace information about all the compiled and written document files as an array structured as a tree.
+
+ This array structure is close, but not quite completely, the format that YAML requires to build the nav option within the mkdocs.yml file.
+
+!!! example "Example"
+    ```php
+    $tree = $this->buildMkDocsNav('/path/to/project/docs')
+    echo var_export($tree, true);
+    // Possible Output:
+    // [
+    //   'Samsara' => [
+    //     'Roster' => [
+    //       'TemplateFactory' => 'roster/latest/Samsara/Roster/TemplateFactory.md',
+    //       'Roster' => 'roster/latest/Samsara/Roster/Roster.md',
+    //       'App' => 'roster/latest/Samsara/Roster/App.md'
+    //     ]
+    //   ]
+    // ]
+    
+    ```
+
 !!! signature "protected Roster->formatNavArrayRecursive(array $nav)"
     **$nav**
 
@@ -129,7 +160,7 @@
     :   array
 
     description
-    :   *No description available*
+    :   A
 
     **return**
 
@@ -139,6 +170,31 @@
     description
     :   *No description available*
 
+formatNavArrayRecursive() method
+
+ This function takes a tree array from buildMkdocsNav() are returns an array that has been reformatted for the expected YAML structure in a mkdocs.yml file nav setting.
+
+!!! example "Example"
+    ```php
+    $nav = $this->formatNavArrayRecursive($tree)
+    echo var_export($nav, true);
+    // Possible Output:
+    // [
+    //   0 => [
+    //     'Samsara' => [
+    //       0 => [
+    //         'Roster' => [
+    //           0 => ['TemplateFactory' => 'roster/latest/Samsara/Roster/TemplateFactory.md'],
+    //           1 => ['Roster' => 'roster/latest/Samsara/Roster/Roster.md'],
+    //           2 => ['App' => 'roster/latest/Samsara/Roster/App.md']
+    //         ]
+    //       ]
+    //     ]
+    //   ]
+    // ]
+    
+    ```
+
 !!! signature "protected Roster->buildNavArrayRecursive(array $parts, int $depth, string $builtString)"
     **$parts**
 
@@ -167,11 +223,33 @@
     **return**
 
     type
-    :   array|string
+    :   array
 
     description
     :   *No description available*
 
+buildNavArrayRecursive() method
+
+ This function takes a flat array and reorganizes it into a tree structure.
+
+!!! example "Example"
+    ```php
+    $flat = ['Samsara', 'Roster', 'Processors', 'TemplateProcessor'];
+    $leaf = $this->buildNavArrayRecursive($flat);
+    echo var_export($leaf);
+    // Output:
+    // [
+    //   'Samsara' => [
+    //       'Roster' => [
+    //           'Processors' => [
+    //               'TemplateProcessor' => 'roster/latest/Samsara/Roster/Processors/TemplateProcessor.md'
+    //           ]
+    //       ]
+    //   ]
+    // ]
+    
+    ```
+
 !!! signature "protected Roster->traverseDirectories(string $dir)"
     **$dir**
 
@@ -243,7 +321,7 @@
     :   string|null
 
     description
-    :   The default command name or null when no default name is set
+    :   *No description available*
 
 !!! signature "public Command::getDefaultDescription()"
     **return**
@@ -252,7 +330,7 @@
     :   ?string
 
     description
-    :   The default command description or null when no default description is set
+    :   *No description available*
 
 
 
@@ -308,7 +386,7 @@
     :   HelperSet|null
 
     description
-    :   A HelperSet instance
+    :   *No description available*
 
 Gets the helper set.
 
@@ -319,7 +397,7 @@ Gets the helper set.
     :   Application|null
 
     description
-    :   An Application instance
+    :   *No description available*
 
 Gets the application instance for this command.
 
@@ -359,9 +437,7 @@ Checks whether the command is enabled or not in the current environment.
     :   int
 
     description
-    :   The command exit code
-
-
+    :   *No description available*
 
 Runs the command.
 
@@ -384,9 +460,7 @@ Runs the command.
     :   $this
 
     description
-    :   
-
-
+    :   *No description available*
 
 Sets the code to execute when running this command.
 
@@ -443,7 +517,7 @@ Sets an array of argument and option instances.
     :   InputDefinition
 
     description
-    :   An InputDefinition instance
+    :   *No description available*
 
 Gets the InputDefinition attached to this Command.
 
@@ -454,7 +528,7 @@ Gets the InputDefinition attached to this Command.
     :   InputDefinition
 
     description
-    :   An InputDefinition instance
+    :   *No description available*
 
 Gets the InputDefinition to be used to create representations of this Command.
 
@@ -575,9 +649,7 @@ Adds an option.
     :   $this
 
     description
-    :   
-
-
+    :   *No description available*
 
 Sets the name of the command.
 
@@ -634,9 +706,7 @@ Returns the command name.
     :   Command
 
     description
-    :   The current instance
-
-
+    :   *No description available*
 
 !!! signature "public Command->isHidden()"
     **return**
@@ -645,7 +715,7 @@ Returns the command name.
     :   bool
 
     description
-    :   whether the command should be publicly shown or not
+    :   *No description available*
 
 !!! signature "public Command->setDescription(string $description)"
     **$description**
@@ -673,7 +743,7 @@ Sets the description for the command.
     :   string
 
     description
-    :   The description for the command
+    :   *No description available*
 
 Returns the description for the command.
 
@@ -703,7 +773,7 @@ Sets the help for the command.
     :   string
 
     description
-    :   The help for the command
+    :   *No description available*
 
 Returns the help for the command.
 
@@ -714,7 +784,7 @@ Returns the help for the command.
     :   string
 
     description
-    :   The processed help for the command
+    :   *No description available*
 
 Returns the processed help for the command replacing the %command.name% and command.full_name% patterns with the real values dynamically.
 
@@ -735,9 +805,7 @@ Returns the processed help for the command replacing the %command.name% and comm
     :   $this
 
     description
-    :   
-
-
+    :   *No description available*
 
 Sets the aliases for the command.
 
@@ -748,7 +816,7 @@ Sets the aliases for the command.
     :   array
 
     description
-    :   An array of aliases for the command
+    :   *No description available*
 
 Returns the aliases for the command.
 
@@ -769,7 +837,7 @@ Returns the aliases for the command.
     :   string
 
     description
-    :   The synopsis
+    :   *No description available*
 
 Returns the synopsis for the command.
 
@@ -818,9 +886,7 @@ Returns alternative usages of the command.
     :   mixed
 
     description
-    :   The helper value
-
-
+    :   *No description available*
 
 Gets a helper instance by name.
 
diff --git a/src/Samsara/Roster/App.php b/src/Samsara/Roster/App.php
index 9a94a20..df3bbf8 100644
--- a/src/Samsara/Roster/App.php
+++ b/src/Samsara/Roster/App.php
@@ -6,11 +6,19 @@
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
+/**
+ * Class App
+ *
+ * This class configures and sets up the Symfony/Console application so that it
+ * is ready for the command to be executed.
+ *
+ * @package Samsara\Roster
+ */
 class App extends Application
 {
 
     public const NAME = 'Roster Markdown Documentation Generator';
-    public const VERSION = 'v0.1.0-alpha';
+    public const VERSION = 'v0.1.0';
 
     public function __construct()
     {
diff --git a/src/Samsara/Roster/Processors/Base/BaseCodeProcessor.php b/src/Samsara/Roster/Processors/Base/BaseCodeProcessor.php
index a99af15..c55912d 100644
--- a/src/Samsara/Roster/Processors/Base/BaseCodeProcessor.php
+++ b/src/Samsara/Roster/Processors/Base/BaseCodeProcessor.php
@@ -57,8 +57,8 @@ protected function fixOutput($option1, $option2, $option3)
 
     protected function templateLoader(string $templateName)
     {
-        if (isset($this->docBlock) && array_key_exists('roster-template', $this->docBlock->others)) {
-            $this->templateProcessor = TemplateFactory::getTemplate($this->docBlock->others['roster-template']->description);
+        if (isset($this->docBlock) && $this->docBlock->hasTag('roster-template')) {
+            $this->templateProcessor = TemplateFactory::getTemplate($this->docBlock->getLastTag('roster-template')->description);
         } else {
             $this->templateProcessor = TemplateFactory::getTemplate($templateName);
         }
diff --git a/src/Samsara/Roster/Processors/MethodArgumentDetailProcessor.php b/src/Samsara/Roster/Processors/MethodArgumentDetailProcessor.php
index 91d4c02..9afdb4b 100644
--- a/src/Samsara/Roster/Processors/MethodArgumentDetailProcessor.php
+++ b/src/Samsara/Roster/Processors/MethodArgumentDetailProcessor.php
@@ -23,8 +23,10 @@ public function __construct(array $parameters, DocBlockProcessor $docBlockProces
 
         $this->parameters = $parameters;
 
-        foreach ($docBlockProcessor->params as $param) {
-            $this->tags[$param->name] = $param;
+        if ($docBlockProcessor->hasTag('param')) {
+            foreach ($docBlockProcessor->getTag('param') as $param) {
+                $this->tags[$param->name] = $param;
+            }
         }
 
     }
diff --git a/src/Samsara/Roster/Processors/MethodArgumentProcessor.php b/src/Samsara/Roster/Processors/MethodArgumentProcessor.php
index 269f7df..a216d59 100644
--- a/src/Samsara/Roster/Processors/MethodArgumentProcessor.php
+++ b/src/Samsara/Roster/Processors/MethodArgumentProcessor.php
@@ -23,8 +23,10 @@ public function __construct(array $parameters, DocBlockProcessor $docBlockProces
 
         $this->parameters = $parameters;
 
-        foreach ($docBlockProcessor->params as $param) {
-            $this->tags[$param->name] = $param;
+        if ($docBlockProcessor->hasTag('param')) {
+            foreach ($docBlockProcessor->getTag('param') as $param) {
+                $this->tags[$param->name] = $param;
+            }
         }
 
     }
diff --git a/src/Samsara/Roster/Processors/MethodProcessor.php b/src/Samsara/Roster/Processors/MethodProcessor.php
index f76abfd..92f2552 100644
--- a/src/Samsara/Roster/Processors/MethodProcessor.php
+++ b/src/Samsara/Roster/Processors/MethodProcessor.php
@@ -46,9 +46,14 @@ public function compile(): string
             $this->templateProcessor->supplyReplacement('methodArgs', $args);
         }
 
-        if ($this->docBlock->example) {
-            $this->templateProcessor->markHas('Example');
-            $this->templateProcessor->supplyReplacement('methodExample', $this->docBlock->example);
+        if ($this->docBlock->hasTag('example')) {
+            if ($this->docBlock->getTagCount('example') == 1) {
+                $this->templateProcessor->markHas('Example');
+                $this->templateProcessor->supplyReplacement(
+                    'methodExample',
+                    $this->docBlock->getTagIndex('example')->getExampleCodeMDEscaped()
+                );
+            }
         }
 
         if (!empty($this->docBlock->description)) {
@@ -57,8 +62,8 @@ public function compile(): string
         }
 
         $returnType = (string)$this->method->getReturnType();
-        $returnType = $this->fixOutput($returnType, $this->docBlock?->return?->type, '*mixed* (assumed)');
-        $returnDesc = (empty($this->docBlock?->return?->description) ? '*No description available*' : $this->docBlock?->return?->description);
+        $returnType = $this->fixOutput($returnType, $this->docBlock?->getLastTag('return')?->type, '*mixed* (assumed)');
+        $returnDesc = (empty($this->docBlock?->return?->description) ? '*No description available*' : $this->docBlock?->getLastTag('return')?->description);
 
         $this->templateProcessor->supplyReplacement('methodReturnType', $returnType);
         $this->templateProcessor->supplyReplacement('methodReturnDesc', $returnDesc);
diff --git a/src/Samsara/Roster/Processors/PropertyProcessor.php b/src/Samsara/Roster/Processors/PropertyProcessor.php
index 89b7b4c..f88a143 100644
--- a/src/Samsara/Roster/Processors/PropertyProcessor.php
+++ b/src/Samsara/Roster/Processors/PropertyProcessor.php
@@ -44,8 +44,8 @@ public function compile(): string
         $propTypeDoc = '';
         $propTypeCode = '';
 
-        if (isset($this->docBlock->others['var'])) {
-            $propTypeDoc = $this->docBlock->others['var']->type;
+        if ($this->docBlock->hasTag('var')) {
+            $propTypeDoc = $this->docBlock->getLastTag('var')->type;
         }
 
         if ($this->property->hasType()) {
diff --git a/src/Samsara/Roster/Roster.php b/src/Samsara/Roster/Roster.php
index 93aba84..596b78d 100644
--- a/src/Samsara/Roster/Roster.php
+++ b/src/Samsara/Roster/Roster.php
@@ -16,6 +16,17 @@
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\SymfonyStyle;
 
+/**
+ * Class Roster
+ *
+ * This class performs all of the command logic to actually build the documentation with the
+ * right options and in the right order.
+ *
+ * The execute() method is the only one directly invoked by the CLI application, and it dispatches
+ * all other function calls.
+ *
+ * @package Samsara\Roster
+ */
 class Roster extends Command
 {
 
@@ -42,7 +53,13 @@ public function __construct($rootDir)
         parent::__construct();
     }
 
-    protected function configure()
+    /**
+     * configure() method
+     *
+     * Creates all the settings for the console command, including setting up the arguments
+     * and the available options.
+     */
+    protected function configure(): void
     {
         $this
             ->setName('compile')
@@ -116,6 +133,16 @@ protected function configure()
         }
     }
 
+    /**
+     * execute() method
+     *
+     * This function performs all of the application logic. All actions performed by the script are
+     * at least started from this function.
+     *
+     * @param InputInterface $input
+     * @param OutputInterface $output
+     * @return int
+     */
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $this->io = new SymfonyStyle($input, $output);;
@@ -411,7 +438,33 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         return 0;
     }
 
-    protected function buildMkdocsNav(string $baseExportPath): string|array
+    /**
+     * buildMkdocsNav
+     *
+     * This function takes in the base export path and outputs the namespace information
+     * about all the compiled and written document files as an array structured as a tree.
+     *
+     * This array structure is close, but not quite completely, the format that YAML requires
+     * to build the nav option within the mkdocs.yml file.
+     *
+     * Example:
+     * $tree = $this->buildMkDocsNav('/path/to/project/docs')
+     * echo var_export($tree, true);
+     * // Possible Output:
+     * // [
+     * //   'Samsara' => [
+     * //     'Roster' => [
+     * //       'TemplateFactory' => 'roster/latest/Samsara/Roster/TemplateFactory.md',
+     * //       'Roster' => 'roster/latest/Samsara/Roster/Roster.md',
+     * //       'App' => 'roster/latest/Samsara/Roster/App.md'
+     * //     ]
+     * //   ]
+     * // ]
+     *
+     * @param string $baseExportPath The realpath() of the location docs are exported to
+     * @return array And array that is structured as a tree containing all documented namespaces and files
+     */
+    protected function buildMkdocsNav(string $baseExportPath): array
     {
         $list = TemplateFactory::getWrittenFiles();
         $pathParts = [];
@@ -430,6 +483,33 @@ protected function buildMkdocsNav(string $baseExportPath): string|array
         return $navArray;
     }
 
+    /**
+     * formatNavArrayRecursive() method
+     *
+     * This function takes a tree array from buildMkdocsNav() are returns an array that has
+     * been reformatted for the expected YAML structure in a mkdocs.yml file nav setting.
+     *
+     * Example:
+     * $nav = $this->formatNavArrayRecursive($tree)
+     * echo var_export($nav, true);
+     * // Possible Output:
+     * // [
+     * //   0 => [
+     * //     'Samsara' => [
+     * //       0 => [
+     * //         'Roster' => [
+     * //           0 => ['TemplateFactory' => 'roster/latest/Samsara/Roster/TemplateFactory.md'],
+     * //           1 => ['Roster' => 'roster/latest/Samsara/Roster/Roster.md'],
+     * //           2 => ['App' => 'roster/latest/Samsara/Roster/App.md']
+     * //         ]
+     * //       ]
+     * //     ]
+     * //   ]
+     * // ]
+     *
+     * @param array $nav A
+     * @return array
+     */
     protected function formatNavArrayRecursive(array $nav): array
     {
         $formattedNav = [];
@@ -447,7 +527,32 @@ protected function formatNavArrayRecursive(array $nav): array
         return $formattedNav;
     }
 
-    protected function buildNavArrayRecursive(array $parts, int $depth = 0, string $builtString = ''): array|string
+    /**
+     * buildNavArrayRecursive() method
+     *
+     * This function takes a flat array and reorganizes it into a tree structure.
+     *
+     * Example:
+     * $flat = ['Samsara', 'Roster', 'Processors', 'TemplateProcessor'];
+     * $leaf = $this->buildNavArrayRecursive($flat);
+     * echo var_export($leaf);
+     * // Output:
+     * // [
+     * //   'Samsara' => [
+     * //       'Roster' => [
+     * //           'Processors' => [
+     * //               'TemplateProcessor' => 'roster/latest/Samsara/Roster/Processors/TemplateProcessor.md'
+     * //           ]
+     * //       ]
+     * //   ]
+     * // ]
+     *
+     * @param array $parts
+     * @param int $depth
+     * @param string $builtString
+     * @return array
+     */
+    protected function buildNavArrayRecursive(array $parts, int $depth = 0, string $builtString = ''): array
     {
         $navArray = [];
         $diffedPath = str_replace($this->rootDir.'/docs/', '', $this->baseExportPath);