[MAINTENANCE] Update command for database documentation generation

Classes/Command/DbDocs/Generator.php → Classes/Command/DatabaseDocs/Generator.php

@@ -10,16 +10,14 @@
  * LICENSE.txt file that was distributed with this source code.
  */
 
-namespace Kitodo\Dlf\Command\DbDocs;
+namespace Kitodo\Dlf\Command\DatabaseDocs;
 
 use Doctrine\DBAL\Schema\Table;
 use ReflectionClass;
 use ReflectionProperty;
-use RuntimeException;
 use TYPO3\CMS\Core\Database\Schema\Parser\Lexer;
 use TYPO3\CMS\Core\Database\Schema\Parser\Parser;
 use TYPO3\CMS\Core\Database\Schema\SqlReader;
-use TYPO3\CMS\Core\Information\Typo3Version;
 use TYPO3\CMS\Core\Localization\LanguageService;
 use TYPO3\CMS\Core\Localization\LanguageServiceFactory;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
@@ -91,7 +89,9 @@
      * Collect information about relevant tables from `ext_tables.sql` and the
      * Extbase classmap.
      *
-     * @return mixed[] Array of objects with table information
+     * @access public
+     *
+     * @return mixed[] An array of objects with table information
      */
     public function collectTables(): array
     {
@@ -103,8 +103,8 @@
         $result = [];
 
         foreach ($createTableStatements as $statement) {
             $parser = new Parser(new Lexer());
             list($table) = $parser->parse($statement);
 
             $tableName = $table->getName();
             if (!str_starts_with($tableName, 'tx_dlf_')) {
@@ -122,6 +122,8 @@
     /**
      * Get a map from database table names to their domain model class names.
      *
+     * @access public
+     *
      * @return mixed[] Map from table name to fully qualified class name
      */
     public function getTableClassMap(): array
@@ -151,14 +153,15 @@
      * @param Table $table The table to be analyzed
      * @param string|null $className Fully qualified name of the domain model class
      *
-     * @return object Object with table information
+     * @return object An object with table information
      */
     protected function getTableInfo(Table $table, ?string $className): object
     {
         $tableName = $table->getName();
 
         $isPrimary = [];
-        if (!is_null($primaryKey = $table->getPrimaryKey())) {
+        $primaryKey = $table->getPrimaryKey();
+        if ($primaryKey != null) {
             foreach ($primaryKey->getUnquotedColumns() as $primaryColumn) {
                 $isPrimary[$primaryColumn] = true;
             }
@@ -216,6 +219,15 @@
         return $result;
     }
 
+    /**
+     * Extract description from a property doc-comment.
+     *
+     * @access public
+     *
+     * @param string $docComment The doc-comment to be parsed
+     *
+     * @return string The extracted description
+     */
     protected function parsePropertyDocComment(string $docComment): string
     {
         $lines = explode("\n", $docComment);
@@ -230,6 +242,15 @@
         return '';
     }
 
+    /**
+     * Extract description from a class doc-comment
+     *
+     * @access protected
+     *
+     * @param string $docComment The doc-comment to be parsed
+     *
+     * @return string The extracted description
+     */
     protected function parseDocComment(string $docComment): string
     {
         // TODO: Consider using phpDocumentor (though that splits the docblock into summary and description)
@@ -255,7 +276,9 @@
     /**
      * Transform table structure into .rst page.
      *
-     * @param mixed[] $tables Array of table information objects
+     * @access public
+     *
+     * @param mixed[] $tables An array of table information objects
      *
      * @return RstSection The generated .rst page
      */
@@ -270,9 +293,11 @@
 RST);
 
         // Sort tables alphabetically
-        usort($tables, function ($lhs, $rhs) {
-            return $lhs->name <=> $rhs->name;
-        });
+        usort(
+            $tables, function ($lhs, $rhs) {
+                return $lhs->name <=> $rhs->name;
+            }
+        );
 
         foreach ($tables as $tableInfo) {
             $section = $page->subsection();
@@ -297,21 +322,25 @@
                 'description' => 'Description',
             ]];
 
-            $rows = array_map(function ($column) use ($page) {
-                return [
-                    'field' => (
-                        $page->format($column->name, ['bold' => $column->isPrimary])
-                        . "\u{00a0}\u{00a0}"
-                        . $page->format($column->type->getName(), ['italic' => true])
-                    ),
-
-                    'description' => $page->paragraphs([
-                        $page->format($column->feComment, ['italic' => true]),
-                        $column->fieldComment,
-                        $column->sqlComment,
-                    ]),
-                ];
-            }, $tableInfo->columns);
+            $rows = array_map(
+                function ($column) use ($page) {
+                    return [
+                        'field' => (
+                            $page->format($column->name, ['bold' => $column->isPrimary])
+                            . "\u{00a0}\u{00a0}"
+                            . $page->format($column->type->getName(), ['italic' => true])
+                        ),
+
+                        'description' => $page->paragraphs(
+                            [
+                                $page->format($column->feComment, ['italic' => true]),
+                                $column->fieldComment,
+                                $column->sqlComment,
+                            ]
+                        ),
+                    ];
+                }, $tableInfo->columns
+            );
 
             $section->addTable($rows, $header);
         }

Classes/Command/DbDocs/RstSection.php → Classes/Command/DatabaseDocs/RstSection.php

@@ -10,7 +10,7 @@
  * LICENSE.txt file that was distributed with this source code.
  */
 
-namespace Kitodo\Dlf\Command\DbDocs;
+namespace Kitodo\Dlf\Command\DatabaseDocs;
 
 /**
  * Simple utility to write .rst (reStructuredText).
@@ -36,6 +36,8 @@
      *
      * @access public
      *
+     * @static
+     *
      * @param string $text
      * @param array<string, bool> $format
      *
@@ -59,15 +61,19 @@
      *
      * @access public
      *
+     * @static
+     *
      * @param mixed[] $paragraphs
      *
      * @return string
      */
     public static function paragraphs(array $paragraphs): string
     {
-        $paragraphs = array_values(array_filter($paragraphs, function ($entry) {
-            return !empty($entry);
-        }));
+        $paragraphs = array_values(
+            array_filter($paragraphs, function ($entry) {
+                return !empty($entry);
+            })
+        );
 
         return implode("\n\n", $paragraphs);
     }
@@ -117,7 +123,7 @@
     }
 
     /**
-     * Add a field list table to section.
+     * Add a field list table to the section.
      *
      * @access public
      *
@@ -196,13 +202,13 @@
     /**
      * Render header of given level.
      *
-     * @access protected
+     * @access private
      *
      * @param int $level
      *
      * @return string
      */
-    protected function renderHeader(int $level): string
+    private function renderHeader(int $level): string
     {
         $result = '';
 

Classes/Command/DbDocsCommand.php → Classes/Command/DatabaseDocsGenerateCommand.php

@@ -12,7 +12,7 @@
 
 namespace Kitodo\Dlf\Command;
 
-use Kitodo\Dlf\Command\DbDocs\Generator;
+use Kitodo\Dlf\Command\DatabaseDocs\Generator;
 use RuntimeException;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
@@ -31,7 +31,7 @@
  *
  * @access public
  */
-class DbDocsCommand extends Command
+class DatabaseDocsGenerateCommand extends Command
 {
     protected Generator $generator;
 

Configuration/Services.yaml

@@ -7,10 +7,10 @@ services:
   Kitodo\Dlf\:
     resource: '../Classes/*'
 
-  Kitodo\Dlf\Command\DbDocsCommand:
+  Kitodo\Dlf\Command\DatabaseDocsGenerateCommand:
     tags:
       - name: console.command
-        command: 'kitodo:dbdocs'
+        command: 'kitodo:databaseDocsGenerate'
         description: 'Generate database rst file.'
 
   Kitodo\Dlf\Command\DeleteCommand: