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);