chore: add PHPDoc to Enterprise library classes for auto-doc engine #137

New Issue

2026-05-26T04:16:16Z

jmiller commented

2026-05-26 04:16:16 +00:00

Summary

Add PHPDoc blocks to all classes, methods, and properties in the Enterprise library to support the upcoming mokogitea auto-documentation engine (code browser).

Standard

File level (already exists - keep DEFGROUP/INGROUP/BRIEF)

Used for navigation tree grouping in the doc engine.

Class level (ADD)

/**
 * One-line summary.
 *
 * Longer description if needed.
 *
 * @since 08.00.00
 * @see   RelatedClass
 */
class MyClass

Method level (ADD)

/**
 * What this method does.
 *
 * @param array<string, mixed> $config Description
 * @return bool True if valid
 * @throws \RuntimeException When something fails
 *
 * @example
 * $result = $obj->method($input);
 */
public function method(array $config): bool

Required tags

Tag	Where	Purpose
@since	Class/method	Version introduced
@param	Method	Parameter type + description
@return	Method	Return type + description
@throws	Method	Exceptions thrown
@see	Class/method	Cross-references
@deprecated	Class/method	Deprecation notice
@example	Method	Usage example (optional, high-value methods)

Scope

Priority 1 (public API - used by other repos)

lib/Enterprise/CliFramework.php (base class for all CLI tools)
lib/Enterprise/GitPlatformAdapter.php (interface)
lib/Enterprise/ApiClient.php
lib/Enterprise/MokoGiteaAdapter.php
lib/Enterprise/GitHubAdapter.php
lib/Enterprise/ConfigValidator.php
lib/Enterprise/ProjectPluginInterface.php

Priority 2 (internal library)

lib/Enterprise/RepositorySynchronizer.php
lib/Enterprise/RepositoryHealthChecker.php
lib/Enterprise/DefinitionParser.php
lib/Enterprise/PlatformAdapterFactory.php
lib/Enterprise/AuditLogger.php
lib/Enterprise/MetricsCollector.php
lib/Enterprise/SecurityValidator.php
lib/Enterprise/ProjectTypeDetector.php

Priority 3 (plugins)

lib/Enterprise/Plugins/*.php (11 plugins)
lib/Enterprise/AbstractProjectPlugin.php

Priority 4 (CLI tools)

cli/*.php (32 tools - file headers already exist, add class/method docs)
validate/*.php (20 validators)

Rules

Do NOT add PHPDoc to trivial getters/setters unless the return value is non-obvious
Do NOT duplicate information already in the type signature
DO add @since for all public methods
DO add @example for complex or frequently-used methods
DO add @throws for methods that throw exceptions
Keep descriptions concise - one line for simple methods

Context

This feeds the mokogitea auto-documentation engine (similar to code.gitea.io / Rustdoc). The engine will parse both the file-level DEFGROUP/INGROUP/BRIEF headers (for navigation) and PHPDoc (for API reference).

## Summary Add PHPDoc blocks to all classes, methods, and properties in the Enterprise library to support the upcoming mokogitea auto-documentation engine (code browser). ## Standard ### File level (already exists - keep DEFGROUP/INGROUP/BRIEF) Used for navigation tree grouping in the doc engine. ### Class level (ADD) ```php /** * One-line summary. * * Longer description if needed. * * @since 08.00.00 * @see RelatedClass */ class MyClass ``` ### Method level (ADD) ```php /** * What this method does. * * @param array<string, mixed> $config Description * @return bool True if valid * @throws \RuntimeException When something fails * * @example * $result = $obj->method($input); */ public function method(array $config): bool ``` ### Required tags | Tag | Where | Purpose | |-----|-------|---------| | @since | Class/method | Version introduced | | @param | Method | Parameter type + description | | @return | Method | Return type + description | | @throws | Method | Exceptions thrown | | @see | Class/method | Cross-references | | @deprecated | Class/method | Deprecation notice | | @example | Method | Usage example (optional, high-value methods) | ## Scope ### Priority 1 (public API - used by other repos) - [ ] lib/Enterprise/CliFramework.php (base class for all CLI tools) - [ ] lib/Enterprise/GitPlatformAdapter.php (interface) - [ ] lib/Enterprise/ApiClient.php - [ ] lib/Enterprise/MokoGiteaAdapter.php - [ ] lib/Enterprise/GitHubAdapter.php - [ ] lib/Enterprise/ConfigValidator.php - [ ] lib/Enterprise/ProjectPluginInterface.php ### Priority 2 (internal library) - [ ] lib/Enterprise/RepositorySynchronizer.php - [ ] lib/Enterprise/RepositoryHealthChecker.php - [ ] lib/Enterprise/DefinitionParser.php - [ ] lib/Enterprise/PlatformAdapterFactory.php - [ ] lib/Enterprise/AuditLogger.php - [ ] lib/Enterprise/MetricsCollector.php - [ ] lib/Enterprise/SecurityValidator.php - [ ] lib/Enterprise/ProjectTypeDetector.php ### Priority 3 (plugins) - [ ] lib/Enterprise/Plugins/*.php (11 plugins) - [ ] lib/Enterprise/AbstractProjectPlugin.php ### Priority 4 (CLI tools) - [ ] cli/*.php (32 tools - file headers already exist, add class/method docs) - [ ] validate/*.php (20 validators) ## Rules - Do NOT add PHPDoc to trivial getters/setters unless the return value is non-obvious - Do NOT duplicate information already in the type signature - DO add @since for all public methods - DO add @example for complex or frequently-used methods - DO add @throws for methods that throw exceptions - Keep descriptions concise - one line for simple methods ## Context This feeds the mokogitea auto-documentation engine (similar to code.gitea.io / Rustdoc). The engine will parse both the file-level DEFGROUP/INGROUP/BRIEF headers (for navigation) and PHPDoc (for API reference).

jmiller commented

2026-05-26 04:16:19 +00:00

Branch created: feature/137-chore-add-phpdoc-to-enterprise-library-c

git fetch origin
git checkout feature/137-chore-add-phpdoc-to-enterprise-library-c

Branch created: [`feature/137-chore-add-phpdoc-to-enterprise-library-c`](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/src/branch/feature/137-chore-add-phpdoc-to-enterprise-library-c) ```bash git fetch origin git checkout feature/137-chore-add-phpdoc-to-enterprise-library-c ```

jmiller referenced this issue from a commit

2026-05-26 04:26:11 +00:00

chore: add PHPDoc to Priority 1 Enterprise classes

jmiller referenced this issue

2026-05-26 04:29:16 +00:00

chore: PHPDoc Priority 1 + Coding Standards wiki #138

jmiller commented

2026-05-26 19:42:06 +00:00

Proof

PHPDoc added to all 4 classes that were missing class-level docs:

cli/joomla_release.php — class JoomlaRelease
lib/Enterprise/ConfigValidator.php — class ConfigValidator
validate/check_repo_health.php — class RepoHealthChecker
validate/check_wiki_health.php — class CheckWikiHealth

Commit 07ea171 on dev.

## Proof PHPDoc added to all 4 classes that were missing class-level docs: - `cli/joomla_release.php` — class JoomlaRelease - `lib/Enterprise/ConfigValidator.php` — class ConfigValidator - `validate/check_repo_health.php` — class RepoHealthChecker - `validate/check_wiki_health.php` — class CheckWikiHealth Commit 07ea171 on dev.

jmiller closed this issue

2026-05-26 19:42:06 +00:00

Sign in to join this conversation.

Priority Low

Type Task

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: MokoConsulting/mokoplatform#137