DOC-002: Missing `@param` / `@return` / `@throws` on Public API Methods

[s2x]

| Priority | High |
| Status | Open |

Problem

Over 100 public methods across src/ZVec.php lack PHPDoc annotations for parameters, return types, or thrown exceptions. Per AGENTS.md rules: "Use PHPDoc @param / @return only when PHP's type system is insufficient". However, ~40 methods have complex generic arrays (@return ZVecDoc[]), nullable conditional returns, or @throws ZVecException that PHP 8.1 typed signatures cannot express.

This causes:

• No IDE autocomplete for array-of-object return types
• No static analysis awareness of thrown exceptions
• No inline parameter descriptions (e.g., what "topk=10" means in context)

Affected Code

Tier 1 — Lifecycle methods (highest usage, highest risk)

Method	File:Line	Missing
ZVec::init()	See DOC-005 (separate)	12 parameters, use/see cross-refs
ZVec::create()	src/ZVec.php	@param $schema, @return self, @throws
ZVec::open()	src/ZVec.php	@param $path, @return self, @throws
ZVec::close()	src/ZVec.php	@throws, lifecycle behavior note
ZVec::destroy()	src/ZVec.php	@throws, segfault warning post-destroy

Tier 2 — Query methods (complex return types)

Method	File:Line	Missing
ZVec::query()	src/ZVec.php	@param for 13 params, conditional @return ZVecDoc[]|ZVecRerankedDoc[]
ZVec::queryByFilter()	src/ZVec.php	@param $filter, @return
ZVec::queryMulti()	src/ZVec.php	@param multi-vector params
ZVec::groupByQuery()	src/ZVec.php	@param group-by specific params
ZVec::queryVector()	src/ZVec.php	@param $queryObject

Tier 3 — Schema/document methods (bulk, 50+ methods)

Method group	Missing
ZVec::addColumn{Int64,String,Float,Double,Bool}() (8)	@param, @return self, @throws
ZVec::alterColumn(), dropColumn(), renameColumn()	@param for nullable/type rename
ZVecSchema::add{Int64,String,Float,Double,Bool,VectorFp32,...}() (20+)	@param type-specific, @return self
ZVecDoc::set{Int64,String,Float,Double,...}() (20+)	@param $value type-specific range/format, @return self
ZVecDoc::get{Int64,String,Float,Double,...}() (20+)	@return types via generic array
ZVecIndexParams::for{Hnsw,Flat,Ivf,Vamana,HnswRabitq}() (6)	@param per index type

Requirements

Per AGENTS.md:

• Use @param only when PHP type system is insufficient (generics, descriptions)
• Use @return only for generic collections: @return ZVecDoc[], @return ZVecRerankedDoc[]
• Use @throws ZVecException on ALL methods that call FFI (see DOC-003)
• Do NOT add redundant @param/@return that repeats the typed signature

Implementation

Template for methods returning ZVecDoc[] (e.g., query(), fetch())

/**
 * Query the collection for similar vectors.
 *
 * @param string|ZVecVectorQuery $fieldName Vector field name or pre-built query object
 * @param int $topk Number of nearest neighbors to return (1-10000)
 * @param string|null $filter Optional filter expression in zvec filter syntax
 * @param ZVecReRanker|null $reranker Optional re-ranker for result refinement
 * @param int $offset Number of results to skip (for pagination)
 * @throws ZVecException On FFI error or invalid parameters
 * @return ZVecDoc[]|ZVecRerankedDoc[] Array of result documents; if $reranker
 *                                      is set, returns ZVecRerankedDoc[]
 */
public function query(
    string|ZVecVectorQuery $fieldName,
    int $topk = 10,
    // ...
): array

Template for fluent setters (ZVecDoc, ZVecSchema)

/**
 * Set string field value on the document.
 *
 * @param string $fieldName Field name as defined in schema
 * @param string $value String value to set
 * @return self For method chaining
 */
public function setString(string $fieldName, string $value): static

Template for factory methods (ZVecIndexParams)

/**
 * Create HNSW index parameters.
 *
 * @param int $metricType One of METRIC_L2, METRIC_IP, METRIC_COSINE, METRIC_MIPSL2
 * @param int $m Maximum number of connections per node (default: 50)
 * @param int $efConstruction Construction-time dynamic range (default: 500)
 * @param int $efSearch Search-time dynamic range (0 = auto, default: 0)
 * @param int $quantizeType One of QUANTIZE_UNDEFINED, QUANTIZE_FP16, QUANTIZE_INT8,
 *                           QUANTIZE_INT4 (default: QUANTIZE_UNDEFINED)
 * @throws ZVecException On invalid parameter combinations
 * @return self
 */
public static function forHnsw(
    int $metricType = self::METRIC_L2,
    int $m = 50,
    // ...
): static

Template for getters returning scalar or nullable

/**
 * Get int64 field value from the document.
 *
 * @param string $fieldName Field name as defined in schema
 * @return int|null Field value, or null if the field is null/not set
 */
public function getInt64(string $fieldName): ?int

Verification

1. Every public method that takes non-trivial parameters has @param with description.
2. Every method returning ZVecDoc[] or ZVecRerankedDoc[] has @return with generic array syntax.
3. Every method calling FFI has @throws ZVecException.
4. No method has redundant PHPDoc that repeats exact type signature without additional info.
5. Fluent methods (return self/static) have @return self.

Acceptance Criteria

• Implementation: Add @param/@return/@throws PHPDoc to ~40 public methods in src/ZVec.php — Tier 1 lifecycle methods (create, open, close, destroy), Tier 2 query methods (query, queryByFilter, queryMulti, groupByQuery, queryVector), Tier 3 schema/doc methods (addColumn*, alterColumn, ZVecSchema::add*, ZVecDoc::set*/get*, ZVecIndexParams::for*)
• Functional tests: Run php -l src/ZVec.php to validate syntax; grep for @return ZVecDoc[] to confirm generic array annotations; grep for @throws ZVecException on all FFI-calling methods
• Documentation review: No redundant PHPDoc that merely repeats the type signature without additional description; @return self on all fluent setters; @throws ZVecException present on every FFI-calling method
• Changelog: CHANGELOG.md entry under ### Added