[RFC]: Mark PhpDb\Sql abstract classes and interfaces @api or @internal #214

Proposed Version

Next minor

Basic Information

Mago reports 16 missing-api-or-internal findings in src/Sql, all baselined. Each one is an abstract class or interface without an @api or @internal annotation:

• Abstract classes: AbstractSql, AbstractPreparableSql, AbstractExpression, Ddl\Column\{AbstractLengthColumn, AbstractPrecisionColumn, AbstractTimestampColumn}, Ddl\Constraint\AbstractConstraint, Ddl\Index\AbstractIndex
• Interfaces: SqlInterface, PreparableSqlInterface, ExpressionInterface, ArgumentInterface, PredicateInterface, Platform\PlatformDecoratorInterface, Ddl\Column\ColumnInterface, Ddl\Constraint\ConstraintInterface

Background

These are the types the driver packages and applications build on: decorators extend the statement classes through AbstractSql and AbstractPreparableSql, and implement PlatformDecoratorInterface (see #175). Metadata marked its source classes @api.

Considerations

• The annotations are documentation only, with no runtime effect.
• @api commits to keeping a type's public and protected surface stable within a minor release. @internal tells consumers not to depend on it.

Proposal(s)

1. Mark every interface above @api.
2. Mark the abstract classes @api, since drivers extend them.
3. Mark protected methods of AbstractSql that only the library itself calls @internal, so they can change without a major release.

Appendix/Additional Info

Finding counts are from mago analyze --ignore-baseline src/Sql once the docblock typing in #204 is applied.