refactor(cli_tools): Deprecated CommandDocumentationGenerator

[christerswahn]

CommandDocumentationGenerator is highly use case specific, no longer used by cloud, and will be removed from this package in the future as it does not fit with general purpose components and is not a priority to develop into one.

Summary by CodeRabbit

• Chores

  • Marked the command documentation generator as deprecated; it will be removed in a future release. Plan migration if you rely on this component.

• Tests

  • Suppressed a deprecation-related lint in the test suite to avoid noise from the newly deprecated component.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a deprecation annotation to the public class CommandDocumentationGenerator and suppressed the corresponding deprecation lint in a test file; no behavioral, signature, control-flow, or error-handling changes.

Changes

Cohort / File(s)	Summary
Deprecation annotation packages/cli_tools/lib/src/documentation_generator/documentation_generator.dart	Added @Deprecated('This is highly use case specific and will be removed from this package in the future.') to the CommandDocumentationGenerator class declaration.
Test lint suppression packages/cli_tools/test/documentation_generator/generate_markdown_test.dart	Added // ignore_for_file: deprecated_member_use_from_same_package to suppress deprecation warnings in the test file.

Sequence Diagram(s)

(omitted — changes do not affect control flow)

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "refactor(cli_tools): Deprecated CommandDocumentationGenerator" directly and accurately describes the primary change in the changeset. The main modifications involve adding a @Deprecated annotation to the CommandDocumentationGenerator class and suppressing deprecation warnings in tests, which aligns perfectly with the title's claim of deprecating this class. The title is concise, specific, and uses conventional commit format with a clear scope (cli_tools), making it easy for someone scanning project history to understand that this PR marks the class as deprecated and prepares it for future removal.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch depr-doc-gen

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a22b5f6 and 296738c.

📒 Files selected for processing (2)

• packages/cli_tools/lib/src/documentation_generator/documentation_generator.dart (1 hunks)
• packages/cli_tools/test/documentation_generator/generate_markdown_test.dart (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/cli_tools/lib/src/documentation_generator/documentation_generator.dart

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-06-12T14:55:38.006Z

Learnt from: christerswahn
PR: serverpod/cli_tools#47
File: lib/src/config/options.dart:552-567
Timestamp: 2025-06-12T14:55:38.006Z
Learning: The codebase relies on a recent version of `package:args` where `ArgParser.addFlag` accepts the `hideNegatedUsage` parameter.

Applied to files:

• packages/cli_tools/test/documentation_generator/generate_markdown_test.dart

🔇 Additional comments (1)

packages/cli_tools/test/documentation_generator/generate_markdown_test.dart (1)

1-2: Appropriate lint suppression for testing deprecated functionality.

The file-level suppression correctly silences deprecation warnings from using CommandDocumentationGenerator (line 107), allowing the tests to continue verifying the deprecated functionality until it's removed. This is standard practice for maintaining backwards compatibility.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/cli_tools/lib/src/documentation_generator/documentation_generator.dart (1)

3-4: Improve deprecation message consistency with codebase patterns and clarify for public API users.

The class is publicly exported through the package (via cli_tools.dart → docs_generator.dart), so the deprecation affects external users. Review other deprecations in the codebase (e.g., in packages/config/lib/src/config/config_parser.dart) which follow the pattern of providing migration guidance ("Use X instead").

Update the deprecation message to:

• Provide explicit migration guidance (what should users do instead?)
• Replace "in the future" with a specific version target
• Consider whether test usage needs deprecation handling (currently tests will emit warnings when using this class)

Example improved message:

@Deprecated(
    'This is highly use case specific and will be removed in version 2.0.0. '
    'Please implement custom documentation generation in your own codebase if needed.')

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d6b9670 and a22b5f6.

📒 Files selected for processing (1)

• packages/cli_tools/lib/src/documentation_generator/documentation_generator.dart (1 hunks)

[SandPod]

👍