docs: Lay groundwork for generated API documentation by updating docblocks

[Levdbas]

Issue

The project needs a foundation for a more extensive documentation website in the future. This PR is the first step toward that goal: it establishes a documented public API and a repeatable class-reference generation workflow that a future
documentation site can build on.

ACF Builder's public PHP API is useful but under-documented in generated class references. Many public builder classes and methods had no @api marker, incomplete summaries, or missing @return information. The project also had no repeatable class-reference generation workflow, making it difficult to keep API documentation complete as the builder surface grows.

The documentation examples also needed to reflect the actual ACF Pro field settings. The ACF Builder wiki does not expose every setting available in the installed ACF Pro source, so this PR compares the field declarations against acf_render_field_setting() and documents the additional supported options where they map directly to existing builder methods.

Solution

Documentation tooling

• Added Timber Teak as a development dependency.

• Added the docs:classes Composer script:

  composer docs:classes

• Configured generated docs/reference output to remain ignored rather than committed as source.

• Regenerated the class references locally to verify the documentation surface.

Coding standards tooling (PHPCS)

• Added squizlabs/php_codesniffer, wp-coding-standards/wpcs, and dealerdirect/phpcodesniffer-composer-installer as development dependencies, relaxing the php_codesniffer constraint to ^3.13.5 || ^4.0 so WPCS can be installed alongside it.

• Added phpcs.xml.dist, a ruleset based on WordPress-Core and a trimmed-down WordPress-Docs, relaxed for use as a general-purpose PSR-4 Composer library rather than a WordPress plugin/theme:

  • Keeps the existing PSR-2 style (spaces for indentation, short array syntax, no forced WordPress array/function-call padding).
  • Drops WordPress-specific naming rules (file names, snake_case functions/variables, Yoda conditions) that don't apply to a PSR-4 library.
  • Keeps docblock formatting sniffs (spacing, @var presence, @param/@throws capitalization and full stops) without requiring a full doc block rewrite everywhere.
  • Explicitly enforces spaces over tabs for indentation.

• Added the cs and cs:fix Composer scripts:

  composer cs
  composer cs:fix

• Fixed all resulting PHPCS findings across src/ and tests/: missing/incomplete docblocks, @throws/@param punctuation and capitalization, missing @param types, stray tabs, and trailing whitespace.

Automated cleanup (Rector)

• Ran composer rector:fix to apply the project's configured Rector rule set across the builders, transforms, and test suite, simplifying redundant code (e.g. collapsing unnecessary conditionals and closures) without changing behavior.

Public API annotations

Added @api annotations to the public builder surface, including:

• Builder, NamedBuilder, and ParentDelegationBuilder contracts/base class.
• FieldsBuilder, FieldBuilder, ChoiceFieldBuilder, ConditionalBuilder, GroupBuilder, RepeaterBuilder, FlexibleContentBuilder, TabBuilder, and AccordionBuilder.
• Public constructors, field factories, fluent configuration methods, conditional methods, nested-builder traversal methods, lookup methods, mutation methods, and build methods.

Method documentation

Completed summaries and return formats for public methods so Teak can generate useful method tables and detailed sections. Documentation now covers:

• Field creation and custom field types.
• Text, textarea, number, email, URL, password, WYSIWYG, oEmbed, image, file, gallery, and choice fields.
• Relational fields such as post object, page link, relationship, taxonomy, and user fields.
• Date/time fields, color picker, Google Map, link, range, message, tab, accordion, group, repeater, and flexible content fields.
• Field configuration, wrappers, conditional logic, field lookup, modification, removal, locations, and nested builder traversal.
• Choice helpers such as addChoice(), addChoices(), and setChoices().

Examples use the requested multiline PHPDoc format with fenced PHP snippets and aligned array options.

FieldsBuilder's field-adding methods (addText(), addSelect(), addRepeater(), etc.) now document their $args option in the WordPress hash-notation style, listing every option supported by the underlying ACF field with its type and a short description:

/**
 * @param string $name
 * @param array $args {
 *     Field configuration options.
 *
 *     @type array<string, string> $choices Array of choice value => label pairs.
 *     @type string $default_value Default selected value.
 *     @type string $return_format Format of the returned value: `value` or `label`.
 *     @type int|bool $allow_null Whether to allow an empty selection.
 *     ...
 * }
 */

This is an example on how the docs now automatically generate:

addButtonGroup()

addButtonGroup( string $name, array $args = [] )

Returns: \StoutLogic\AcfBuilder\FieldBuilder

Name	Type	Description
$name	string
$args	array	field configuration

PHP

$fields->addButtonGroup('alignment', [
    'choices'                   => ['left' => 'Left', 'center' => 'Center'],
    'default_value'             => '',
    'return_format'             => 'value',
    'allow_null'                => 0,
    'layout'                    => 'horizontal',
]);

ACF Pro option coverage

The field examples include settings found in the installed ACF Pro field declarations, including options such as:

• Media limits, MIME types, library restrictions, preview sizes, and return formats.
• Choice defaults, layouts, nullability, AJAX, custom options, and return formats.
• Relational post type, post status, taxonomy, filters, min/max, and element settings.
• Taxonomy term loading/saving and field type settings.
• Date and time display/return formats, first day, and current-date defaults.
• Repeater pagination, rows per page, collapsed field, layout, min/max, and button label.
• Flexible content min/max and button label.

The source-only ACF field types icon_picker and clone do not have matching builder factories, so they are not represented as options on an existing method.

Exception organization

Moved the exception classes into src/Exceptions and updated their namespace to StoutLogic\AcfBuilder\Exceptions:

• FieldNameCollisionException
• FieldNotFoundException
• LayoutNotFoundException
• ModifyFieldReturnTypeException

Updated source imports, tests, and generated documentation behavior accordingly. The exception classes are intentionally not marked with @api; they are documented through @throws on the public methods that emit them.

Impact

Runtime behavior

The builder algorithms and generated ACF configuration behavior are unchanged. The documentation and Teak additions do not affect production execution.

The exception namespace move is the compatibility-sensitive part of this PR. Consumers that import or catch the old root-namespace exception classes must update imports to the new namespace, for example:

use StoutLogic\AcfBuilder\Exceptions\FieldNotFoundException;

The exception class names and inheritance remain unchanged apart from the namespace.

Dependencies

Timber Teak and its documentation dependencies are development-only. The runtime package requirements are not changed by the documentation work in this PR. The Composer lockfile is updated to include Teak and the resolved dependency graph.

PHPCS, WPCS, and their Composer installer plugin are also development-only additions. php_codesniffer's constraint is widened (^3.13.5 || ^4.0) to allow WPCS to resolve; production requirements are unchanged.

Generated output

The class-reference Markdown files are generated artifacts and are ignored by Git. They can be reproduced with composer docs:classes.

Example:

addButtonGroup()

addButtonGroup( string $name, array $args = [] )

Returns: \StoutLogic\AcfBuilder\FieldBuilder

Name	Type	Description
$name	string
$args	array	field configuration

PHP

$fields->addButtonGroup('alignment', [
    'choices'                   => ['left' => 'Left', 'center' => 'Center'],
    'default_value'             => '',
    'return_format'             => 'value',
    'allow_null'                => 0,
    'layout'                    => 'horizontal',
]);

Performance

No production performance impact is expected. The only new runtime-facing code changes are namespace imports for existing exception classes.

Usage changes

Most users do not need to change their builder usage. The public methods retain their existing names and behavior.

Users catching or importing the moved exceptions must migrate from the old namespace:

// Before
use StoutLogic\AcfBuilder\FieldNotFoundException;

// After
use StoutLogic\AcfBuilder\Exceptions\FieldNotFoundException;

To regenerate API references locally:

composer install
composer docs:classes

Testing

Automated validation completed on the rebased branch:

composer test
composer docs:classes
composer cs
composer rector

Results:

• PHPUnit: 168 tests, 235 assertions, all passing.
• Teak class-reference generation completed successfully for all public builder classes.
• PHPCS (composer cs) passes cleanly against src/ and tests/ with the new phpcs.xml.dist ruleset.
• PHP lint passed for the source files during the rebase validation.
• git diff --check passed during the documentation validation.

The tests cover the updated exception imports, field manager behavior, field builder behavior, nested builders, conditional logic, repeaters, flexible content, and generated configuration behavior.

No manual WordPress/ACF admin verification was performed. The change is primarily documentation/tooling work, with the exception namespace move covered by the existing PHPUnit suite.

Considerations

I might not have documented every public method yet. As this is a big task I would love to see if others could help in this matter as well.