From 3f3b1f79a0028dd35db35f582b89298bc6df0256 Mon Sep 17 00:00:00 2001
From: Jonathan Miller <jmiller-moko@noreply.git.mokoconsulting.tech>
Date: Mon, 25 May 2026 23:26:07 -0500
Subject: [PATCH] chore: add PHPDoc to Priority 1 Enterprise classes

Added @since, @param, @see tags to:
- CliFramework: class-level @since, 2 undocumented methods
- GitHubAdapter: class @since/@see, constructor @param, property docs
- MokoGiteaAdapter: class @since/@see, constructor @param, property docs
- ApiClient: class @since

Wiki: created Coding-Standards page with full PHPDoc standard,
PHPCS exclusion rationale, and file structure patterns.

Partial progress on #137

Authored-by: Moko Consulting
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 lib/Enterprise/ApiClient.php        |  2 ++
 lib/Enterprise/CliFramework.php     | 13 +++++++++++++
 lib/Enterprise/GitHubAdapter.php    |  7 ++++++-
 lib/Enterprise/MokoGiteaAdapter.php | 10 +++++++++-
 phpstan-baseline.neon               | 10 ++--------
 5 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/lib/Enterprise/ApiClient.php b/lib/Enterprise/ApiClient.php
index 8fb5f1a..eb6a369 100644
--- a/lib/Enterprise/ApiClient.php
+++ b/lib/Enterprise/ApiClient.php
@@ -92,6 +92,8 @@ class CircuitBreakerOpen extends RuntimeException
  * );
  * $response = $client->get('/repos/owner/repo');
  * ```
+ *
+ * @since 04.00.00
  */
 class ApiClient
 {
diff --git a/lib/Enterprise/CliFramework.php b/lib/Enterprise/CliFramework.php
index f786ec5..52e08f9 100644
--- a/lib/Enterprise/CliFramework.php
+++ b/lib/Enterprise/CliFramework.php
@@ -716,6 +716,9 @@ class ValidationCLI extends CLIApp
  * Lifecycle: configure() -> parseArguments() -> printBanner() -> initialize() -> run()
  *
  * All new scripts must extend CliFramework and implement configure() + run().
+ *
+ * @since   04.00.15
+ * @see     CLIApp Legacy base class (deprecated)
  */
 abstract class CliFramework
 {
@@ -932,6 +935,11 @@ abstract class CliFramework
     // Argument parsing (internal)
     // =========================================================================
 
+    /**
+     * Parse CLI arguments from $_SERVER['argv'] into registered argument definitions.
+     *
+     * @since 04.00.15
+     */
     private function parseArguments(): void
     {
         $argv = array_slice($_SERVER['argv'] ?? [], 1);
@@ -970,6 +978,11 @@ abstract class CliFramework
     // Help screen
     // =========================================================================
 
+    /**
+     * Print auto-generated help screen from registered arguments.
+     *
+     * @since 04.00.15
+     */
     protected function printHelp(): void
     {
         $w = $this->termWidth();
diff --git a/lib/Enterprise/GitHubAdapter.php b/lib/Enterprise/GitHubAdapter.php
index efddeb4..d34e701 100644
--- a/lib/Enterprise/GitHubAdapter.php
+++ b/lib/Enterprise/GitHubAdapter.php
@@ -32,12 +32,17 @@ use RuntimeException;
  * - Workflow dir: .github/workflows
  *
  * @package MokoStandards\Enterprise
- * @version 04.06.10
+ * @since   04.06.10
+ * @see     GitPlatformAdapter
  */
 class GitHubAdapter implements GitPlatformAdapter
 {
+    /** @var ApiClient HTTP client for GitHub API calls. */
     private ApiClient $apiClient;
 
+    /**
+     * @param ApiClient $apiClient Configured API client for api.github.com
+     */
     public function __construct(ApiClient $apiClient)
     {
         $this->apiClient = $apiClient;
diff --git a/lib/Enterprise/MokoGiteaAdapter.php b/lib/Enterprise/MokoGiteaAdapter.php
index 9cc014d..79b0c5c 100644
--- a/lib/Enterprise/MokoGiteaAdapter.php
+++ b/lib/Enterprise/MokoGiteaAdapter.php
@@ -34,13 +34,21 @@ use RuntimeException;
  * - Workflow dir: .mokogitea/workflows
  *
  * @package MokoStandards\Enterprise
- * @version 04.06.10
+ * @since   04.06.10
+ * @see     GitPlatformAdapter
  */
 class MokoGiteaAdapter implements GitPlatformAdapter
 {
+    /** @var ApiClient HTTP client for Gitea API calls. */
     private ApiClient $apiClient;
+
+    /** @var string Base URL for Gitea API (e.g. https://git.mokoconsulting.tech/api/v1). */
     private string $baseUrl;
 
+    /**
+     * @param ApiClient $apiClient Configured API client
+     * @param string    $baseUrl   Gitea API base URL
+     */
     public function __construct(ApiClient $apiClient, string $baseUrl = 'https://git.mokoconsulting.tech/api/v1')
     {
         $this->apiClient = $apiClient;
diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon
index 3ee856b..4f77b05 100644
--- a/phpstan-baseline.neon
+++ b/phpstan-baseline.neon
@@ -415,15 +415,9 @@ parameters:
 			path: cli/theme_lint.php
 
 		-
-			message: '#^Offset ''alpha''\|''beta''\|''development''\|''rc''\|''stable'' on array\{stable\: '''', rc\: ''\-rc'', beta\: ''\-beta'', alpha\: ''\-alpha'', development\: ''\-dev''\} on left side of \?\? always exists and is not nullable\.$#'
+			message: '#^Offset ''alpha''\|''beta''\|''development''\|''rc''\|''stable'' on array\{stable\: ''stable'', rc\: ''rc'', beta\: ''beta'', alpha\: ''alpha'', development\: ''dev''\} on left side of \?\? always exists and is not nullable\.$#'
 			identifier: nullCoalesce.offset
-			count: 1
-			path: cli/updates_xml_build.php
-
-		-
-			message: '#^Offset ''alpha''\|''beta''\|''development''\|''rc''\|''stable'' on array\{stable\: ''stable'', rc\: ''rc'', beta\: ''beta'', alpha\: ''alpha'', development\: ''development''\} on left side of \?\? always exists and is not nullable\.$#'
-			identifier: nullCoalesce.offset
-			count: 1
+			count: 2
 			path: cli/updates_xml_build.php
 
 		-