refactor: rename dockblock references to docheader

coisa · coisa · commit 94b74e575787 · 2026-04-26T18:22:43.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,8 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Align the standards pipeline to invoke PHPDoc checks via the `php-cs-fixer` command name/alias and route standards cache to `.dev-tools/cache/php-cs-fixer`, preserving backwards compatibility for existing `dockblock`-style entry points.
-- Rename the command entry point from `standards:phpdoc` to `standards:dockblock` and keep both `dockblock` and `php-cs-fixer` aliases for compatibility (`standards:phpdoc` is intentionally not kept as a command name).
+- Align the standards pipeline to invoke PHPDoc checks via the `php-cs-fixer` command name/alias and route standards cache to `.dev-tools/cache/php-cs-fixer`, preserving backwards compatibility for existing `docheader`-style entry points.
+- Rename the command entry point from `standards:phpdoc` to `standards:docheader` and keep both `docheader` and `php-cs-fixer` aliases for compatibility (`standards:phpdoc` is intentionally not kept as a command name).
 
 ## [1.22.3] - 2026-04-25
 
diff --git a/README.md b/README.md
@@ -107,7 +107,7 @@ composer code-style
 composer refactor
 
 # Check and fix PHPDoc comments
-composer phpdoc
+composer docheader
 
 # Generate HTML API documentation using phpDocumentor
 composer docs
diff --git a/docs/advanced/rector-and-phpdoc.rst b/docs/advanced/rector-and-phpdoc.rst
@@ -1,14 +1,14 @@
-Rector and PHPDoc Automation
-============================
+Rector and Docheader Automation
+===============================
 
 The package uses two different Rector entry points, and that difference matters
 when you are trying to understand why a rule did or did not run.
 
-``refactor`` Versus ``phpdoc``
+``refactor`` Versus ``docheader``
 ------------------------------
 
 - ``refactor`` uses the full ``rector.php`` file.
-- ``phpdoc`` runs PHP-CS-Fixer first and then executes Rector with
+- ``docheader`` runs PHP-CS-Fixer first and then executes Rector with
   ``--only \FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``.
 
 Rules Shipped by the Package
@@ -19,7 +19,7 @@ Rules Shipped by the Package
 
    * - Rule
      - Enabled in packaged ``rector.php``
-     - Used directly by ``phpdoc``
+     - Used directly by ``docheader``
      - Purpose
    * - ``FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``
      - Yes
@@ -45,7 +45,7 @@ rules when ``thecodingmachine/safe`` is installed.
 Why ``.docheader`` Appears Automatically
 ----------------------------------------
 
-The ``phpdoc`` command creates ``.docheader`` in the consumer root when it is
+The ``docheader`` command creates ``.docheader`` in the consumer root when it is
 missing. The template comes from the packaged file and the package name is
 rewritten to match the current project whenever Composer metadata is
 available.
diff --git a/docs/api/commands.rst b/docs/api/commands.rst
@@ -37,8 +37,9 @@ subprocess execution is needed.
      - ``refactor``
      - Runs Rector with local or packaged configuration.
    * - ``FastForward\DevTools\Console\Command\PhpDocCommand``
-     - ``phpdoc``
-     - Runs PHP-CS-Fixer and a focused Rector PHPDoc pass.
+     - ``standards:docheader``
+     - Runs PHP-CS-Fixer and a focused Rector PHPDoc pass. Supported aliases:
+       ``docheader`` and ``php-cs-fixer``.
    * - ``FastForward\DevTools\Console\Command\CodeStyleCommand``
      - ``code-style``
      - Runs Composer Normalize and ECS.
diff --git a/docs/commands/phpdoc.rst b/docs/commands/phpdoc.rst
@@ -1,12 +1,13 @@
-phpdoc
-======
+docheader
+=========
 
 Checks and fixes PHPDoc comments.
 
 Description
 -----------
 
-The ``phpdoc`` command coordinates PHPDoc checking and fixing using:
+The ``docheader`` command coordinates PHPDoc checking and fixing using:
+(alias ``docheader`` and ``php-cs-fixer``)
 
 - PHP-CS-Fixer - fixes PHPDoc formatting
 - Rector with ``AddMissingMethodPhpDocRector`` - adds missing method PHPDoc
@@ -18,10 +19,11 @@ Usage
 
 .. code-block:: bash
 
-   composer phpdoc
-   composer phpdoc [options]
-   composer dev-tools phpdoc -- [options]
-   vendor/bin/dev-tools phpdoc [options]
+   composer docheader
+   composer php-cs-fixer
+   composer docheader [options]
+   composer dev-tools docheader -- [options]
+   vendor/bin/dev-tools docheader [options]
 
 Arguments
 ---------
@@ -61,25 +63,25 @@ Check PHPDocs (dry-run):
 
 .. code-block:: bash
 
-   composer phpdoc
+   composer docheader
 
 Fix PHPDocs automatically:
 
 .. code-block:: bash
 
-   composer phpdoc --fix
+   composer docheader --fix
 
 Check specific directory:
 
 .. code-block:: bash
 
-   composer phpdoc ./src
+   composer docheader ./src
 
 Check without cache:
 
 .. code-block:: bash
 
-   composer phpdoc --no-cache
+   composer docheader --no-cache
 
 Exit Codes
 ---------
diff --git a/docs/commands/standards.rst b/docs/commands/standards.rst
@@ -9,7 +9,7 @@ Description
 The ``standards`` command runs the full quality pipeline:
 
 1. ``refactor`` - Rector code refactoring
-2. ``phpdoc`` - PHPDoc checks and fixes
+2. ``docheader`` - PHPDoc checks and fixes
 3. ``code-style`` - Code style checking
 4. ``reports`` - Documentation and test reports
 
@@ -68,10 +68,10 @@ Behavior
 - Cache stays enabled by default for nested cache-aware phases; omit both flags
   to keep the command default, pass ``--cache`` to force it on, and pass
   ``--no-cache`` to force it off.
-- The explicit cache intent is propagated to the nested ``phpdoc`` and
+- The explicit cache intent is propagated to the nested ``docheader`` and
   ``reports`` phases. ``refactor`` and ``code-style`` do not consume this
   contract.
-- When ``--cache-dir`` is provided, ``phpdoc`` and ``reports`` receive nested
+- When ``--cache-dir`` is provided, ``docheader`` and ``reports`` receive nested
   cache directories under that base path. When it is omitted, each nested tool
   keeps its own default cache directory.
 - Progress output is disabled by default across nested phases; use
diff --git a/docs/configuration/overriding-defaults.rst b/docs/configuration/overriding-defaults.rst
@@ -38,7 +38,7 @@ Commands and Their Configuration Files
    * - ``dependencies``
      - ``composer-dependency-analyser.php``
      - Falls back to the packaged Composer Dependency Analyser configuration.
-   * - ``phpdoc``
+   * - ``docheader``
      - ``.php-cs-fixer.dist.php`` and ``rector.php``
      - Falls back to the packaged files; ``.docheader`` is created locally
        when missing.
@@ -62,7 +62,7 @@ A Practical Example
 -------------------
 
 To customize Rector for one library, create ``rector.php`` in the consumer
-project root. The ``refactor`` command and the Rector phase inside ``phpdoc``
+project root. The ``refactor`` command and the Rector phase inside ``docheader``
 will use that file instead of the packaged default.
 
 Extending ECS Configuration
diff --git a/docs/configuration/tooling-defaults.rst b/docs/configuration/tooling-defaults.rst
@@ -14,16 +14,16 @@ create them on day one.
      - ``code-style``
      - Fallback ECS configuration.
    * - ``rector.php``
-     - ``refactor`` and ``phpdoc``
+     - ``refactor`` and ``docheader``
      - Fallback Rector configuration.
    * - ``phpunit.xml``
      - ``tests``
      - Registers ``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``.
    * - ``.php-cs-fixer.dist.php``
-     - ``phpdoc``
+     - ``docheader``
      - Controls header and PHPDoc fixer behavior.
    * - ``.docheader``
-     - ``phpdoc``
+     - ``docheader``
      - Created into the consumer root on demand when missing.
    * - ``.editorconfig``
      - ``dev-tools:sync``
diff --git a/docs/running/specialized-commands.rst b/docs/running/specialized-commands.rst
@@ -179,15 +179,15 @@ Important details:
 - ``--json`` and ``--pretty-json`` forward ``--output-format json`` to Rector
   and disable its progress bar.
 
-``phpdoc``
-----------
+``docheader`` (alias: ``php-cs-fixer``)
+---------------------------------------
 
 Coordinates PHP-CS-Fixer and a focused Rector pass for missing method PHPDoc.
 
 .. code-block:: bash
 
-   composer phpdoc
-   composer phpdoc --fix
+   composer docheader
+   composer php-cs-fixer --fix
 
 Important details:
 
diff --git a/docs/running/unified-command.rst b/docs/running/unified-command.rst
@@ -14,7 +14,7 @@ Execution Order
 ``standards`` runs these commands in sequence:
 
 1. ``refactor``
-2. ``phpdoc``
+2. ``docheader``
 3. ``code-style``
 4. ``reports``
 
@@ -31,7 +31,7 @@ To allow the tools to modify files, use one of the following entry points:
    composer dev-tools:fix
    vendor/bin/dev-tools --fix
 
-The flag mainly affects ``refactor``, ``phpdoc``, and ``code-style``. The
+The flag mainly affects ``refactor``, ``docheader``, and ``code-style``. The
 reporting steps still run, but they do not use the flag themselves.
 
 When the Unified Command Is the Right Choice
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
@@ -238,7 +238,7 @@ Recovery:
 
 .. code-block:: bash
 
-    composer dev-tools phpdoc
+    composer dev-tools docheader
     composer dev-tools docs
 
 Fix source PHPDoc first, then regenerate docs. Avoid editing generated API
diff --git a/docs/usage/common-workflows.rst b/docs/usage/common-workflows.rst
@@ -11,7 +11,7 @@ Most day-to-day work falls into one of the flows below.
      - What happens
    * - Check everything before a pull request
      - ``composer dev-tools``
-     - Runs ``refactor``, ``phpdoc``, ``code-style``, and ``reports`` in
+     - Runs ``refactor``, ``docheader``, ``code-style``, and ``reports`` in
        order.
    * - Auto-fix what can be changed safely
      - ``composer dev-tools:fix``
diff --git a/src/Console/Command/PhpDocCommand.php b/src/Console/Command/PhpDocCommand.php
@@ -44,8 +44,8 @@
  * Provides operations to inspect, lint, and repair PHPDoc comments across the project.
  * The class MUST NOT be extended and SHALL coordinate tools like PHP-CS-Fixer and Rector.
  */
-#[AsCommand(name: 'standards:dockblock', description: 'Checks and fixes PHPDocs.', aliases: [
-    'dockblock',
+#[AsCommand(name: 'standards:docheader', description: 'Checks and fixes PHPDocs.', aliases: [
+    'docheader',
     'php-cs-fixer',
 ])]
 final class PhpDocCommand extends Command
diff --git a/src/Console/Command/StandardsCommand.php b/src/Console/Command/StandardsCommand.php
@@ -181,7 +181,7 @@ private function getProcessLabel(string $command): string
     {
         return match ($command) {
             'refactor' => 'Refactoring Code with DevTools',
-            'php-cs-fixer', 'dockblock' => 'Checking PHPDoc with DevTools',
+            'php-cs-fixer', 'docheader' => 'Checking PHPDoc with DevTools',
             'code-style' => 'Checking Code Style with DevTools',
             'reports' => 'Generating Reports with DevTools',
             default => 'Running DevTools Command',
