zero-to-prod/docblock-annotator-cli

A cli for annotating Docblocks.

v4.1.0 2025-02-16 00:00 UTC

Requires

• php: >=8.1
• ext-json: *
• symfony/console: ^7.2
• zero-to-prod/data-model: ^81.9
• zero-to-prod/docblock-annotator: ^4.0
• zero-to-prod/package-helper: ^1.1.3

Requires (Dev)

• phpunit/phpunit: <12.0

MIT

• David Smith

• zero-to-prod
• docblock-annotator-cli

README

Contents

• Introduction
• Requirements
• Installation
• Documentation Publishing
  • Automatic Documentation Publishing
• Usage
  • Available Commands
    • docblock-annotator-cli:src
    • docblock-annotator-cli:update-file
    • docblock-annotator-cli:update-directory
• Docker Image
• Local Development
• Image Development
• Contributing

Introduction

A cli for annotating Docblocks.

Requirements

• PHP 8.1 or higher.

Installation

Install Zerotoprod\DocblockAnnotatorCli via Composer:

composer require zero-to-prod/docblock-annotator-cli

This will add the package to your project's dependencies and create an autoloader entry for it.

Documentation Publishing

You can publish this README to your local documentation directory.

This can be useful for providing documentation for AI agents.

This can be done using the included script:

# Publish to default location (./docs/zero-to-prod/docblock-annotator-cli)
vendor/bin/zero-to-prod-docblock-annotator-cli

# Publish to custom directory
vendor/bin/zero-to-prod-docblock-annotator-cli /path/to/your/docs

Automatic Documentation Publishing

You can automatically publish documentation by adding the following to your composer.json:

{
    "scripts": {
        "post-install-cmd": [
            "zero-to-prod-docblock-annotator-cli"
        ],
        "post-update-cmd": [
            "zero-to-prod-docblock-annotator-cli"
        ]
    }
}

Usage

Run this command to see the available commands:

vendor/bin/docblock-annotator-cli list

Available Commands

docblock-annotator-cli:src

Displays the project's GitHub repository URL.

Usage:

vendor/bin/docblock-annotator-cli docblock-annotator-cli:src

Example:

$ vendor/bin/docblock-annotator-cli docblock-annotator-cli:src
https://github.com/zero-to-prod/docblock-annotator-cli

docblock-annotator-cli:update-file

Adds lines to a PHP docblock in a specific file.

Usage:

vendor/bin/docblock-annotator-cli docblock-annotator-cli:update-file [options] <file> [<comments>...]

Arguments:

• file (required) - The PHP file to update
• comments (optional) - The comments to add to the docblock

Options:

• --modifiers - The modifier of the member: public, private, protected (default: public)
• --statements - The statements to annotate: class_method, const, class, class_const, enum_case, enum, function, trait, property, interface (default: all)

Examples:

# Add comments to all public methods in a file
vendor/bin/docblock-annotator-cli docblock-annotator-cli:update-file src/MyClass.php "Added by CLI" "Updated on $(date)"

# Update only private methods with custom comments
vendor/bin/docblock-annotator-cli docblock-annotator-cli:update-file --modifiers=private src/MyClass.php "Private method updated"

# Update only class methods and properties
vendor/bin/docblock-annotator-cli docblock-annotator-cli:update-file --statements=class_method --statements=property src/MyClass.php "Method and property updated"

docblock-annotator-cli:update-directory

Adds lines to PHP docblocks in all files within a directory.

Usage:

vendor/bin/docblock-annotator-cli docblock-annotator-cli:update-directory [options] <directory> [<comments>...]

Alias: docblock-annotator-cli:update

Arguments:

• directory (required) - The directory to update PHP files in
• comments (optional) - The comments to add to the docblock

Options:

• --modifiers - The modifier of the member: public, private, protected (default: public)
• --statements - The statements to annotate: class_method, const, class, class_const, enum_case, enum, function, trait, property, interface (default: all)
• --recursive / --no-recursive - Recursively search for files (default: recursive)

Examples:

# Update all PHP files in src directory with comments
vendor/bin/docblock-annotator-cli docblock-annotator-cli:update-directory src/ "Bulk updated" "$(date)"

# Update only public methods in src directory (non-recursive)
vendor/bin/docblock-annotator-cli docblock-annotator-cli:update-directory --no-recursive --statements=class_method src/ "Public methods updated"

# Use the shorter alias command
vendor/bin/docblock-annotator-cli docblock-annotator-cli:update src/ "Updated via alias"

# Update all statement types with specific modifiers
vendor/bin/docblock-annotator-cli docblock-annotator-cli:update-directory --modifiers=public --modifiers=protected src/ "Updated public and protected members"

Docker Image

You can also run the cli using the docker image:

docker run --rm davidsmith3/docblock-annotator-cli

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.

1. Fork the repository.
2. Create a new branch (git checkout -b feature-branch).
3. Commit changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature-branch).
5. Create a new Pull Request.