docs: add class-level documentation to SKU services #14

New issue

Open

opened 2026-02-20 11:10:01 +00:00 by Clotho · 0 comments

Clotho commented

2026-02-20 11:10:01 +00:00

Member

Issue

Three SKU-related services lack class-level docblocks explaining their purpose and usage.

Affected Files

Services/SkuBuilderService.php - Missing class docblock
Services/SkuParserService.php - Missing class docblock
Services/SkuLineageService.php - Missing class docblock

Current State

Each service has method-level docblocks but no overview explaining:

What the service does
When to use it
SKU format/lineage system (M1/M2/M3 hierarchy)

Required Fix

Add class-level docblocks with:

Purpose and responsibility
Example usage
Reference to SKU format documentation (per TODO.md P3-111)

Example:

/**
 * SKU Parser Service
 *
 * Parses compound SKU strings into structured components.
 * SKUs follow the format: M1[+M2[+M3]][^OPT1:VAL1^OPT2:VAL2]
 *
 * Examples:
 * - Simple: "BASE-PLAN"
 * - Compound: "BASE-PLAN+ADDON1+ADDON2"
 * - With options: "BASE-PLAN^colour:blue^size:large"
 *
 * @see SkuBuilderService For SKU construction
 * @see SkuLineageService For M1/M2/M3 hierarchy validation
 */
class SkuParserService
{
    // ...
}

Per TODO.md P3-111, comprehensive SKU format documentation should be added to CLAUDE.md or docs/.

Priority

Low - Improves developer experience but not blocking.

Created by discovery scan (issue #2)

## Issue Three SKU-related services lack class-level docblocks explaining their purpose and usage. ## Affected Files - `Services/SkuBuilderService.php` - Missing class docblock - `Services/SkuParserService.php` - Missing class docblock - `Services/SkuLineageService.php` - Missing class docblock ## Current State Each service has method-level docblocks but no overview explaining: - What the service does - When to use it - SKU format/lineage system (M1/M2/M3 hierarchy) ## Required Fix Add class-level docblocks with: - Purpose and responsibility - Example usage - Reference to SKU format documentation (per TODO.md P3-111) ### Example: ```php /** * SKU Parser Service * * Parses compound SKU strings into structured components. * SKUs follow the format: M1[+M2[+M3]][^OPT1:VAL1^OPT2:VAL2] * * Examples: * - Simple: "BASE-PLAN" * - Compound: "BASE-PLAN+ADDON1+ADDON2" * - With options: "BASE-PLAN^colour:blue^size:large" * * @see SkuBuilderService For SKU construction * @see SkuLineageService For M1/M2/M3 hierarchy validation */ class SkuParserService { // ... } ``` ## Related Work Per TODO.md P3-111, comprehensive SKU format documentation should be added to CLAUDE.md or docs/. ## Priority Low - Improves developer experience but not blocking. --- _Created by discovery scan (issue #2)_