docs: add class-level PHPDoc to all major classes (closes #60)

CHANGELOG.md

@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **DOC-001: Added class-level PHPDoc to all major classes for IDE tooling** (#60)
+  - Added class-level PHPDoc blocks to all 15 source files: ZVec, ZVecException, ZVecCollectionOptions, ZVecCollectionStats, ZVecFieldSchema, ZVecIndexParams, ZVecQueryInterface, ZVecVectorQuery, ZVecGroupByVectorQuery, ZVecSchema, ZVecDoc, ZVecRerankedDoc, ZVecRrfReRanker, ZVecWeightedReRanker, ZVecReRanker
+  - Each block follows a consistent format: one-line purpose, usage paragraph, and `@see` cross-references
+  - All `@see` references verified against actual methods and classes
+
 - **TEST-007: Memory leak regression tests for FFI memory safety** (#105)
   - Added 5 `.phpt` test files for memory leak regression testing:
     - `test_memory_collection_lifecycle.phpt` — 50x create/open/close/destroy cycle with memory growth tracking

src/ZVec.php

@@ -23,6 +23,19 @@
 require_once __DIR__ . '/ZVecRrfReRanker.php';
 require_once __DIR__ . '/ZVecWeightedReRanker.php';
 
+/**
+ * Main entry point for zvec vector database operations.
+ *
+ * Provides static factory methods (create() / open()) for collection
+ * lifecycle, and wraps the FFI bridge to the zvec C++ library.
+ * Must call init() once before any other operation.
+ *
+ * Lifecycle: init() -> create()/open() -> insert/query -> close()/destroy()
+ *
+ * @see ZVecSchema For defining collection schemas
+ * @see ZVecDoc For creating and manipulating documents
+ * @see ZVecException For error details
+ */
 class ZVec
 {
     private static ?FFI $ffi = null;

src/ZVecCollectionOptions.php

@@ -6,6 +6,16 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Options for creating or opening collections with createWith()/openWith().
+ *
+ * Controls read-only mode, memory-mapped I/O, and buffer size.
+ * Use factory methods readOnly(), readWrite(), or defaults() for
+ * common configurations.
+ *
+ * @see ZVec::createWith()
+ * @see ZVec::openWith()
+ */
 class ZVecCollectionOptions
 {
     public bool $readOnly = false;

src/ZVecCollectionStats.php

@@ -8,6 +8,15 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Structured collection statistics as an object.
+ *
+ * Wraps the FFI stats struct with typed getters for document count,
+ * index count, and per-index completeness. Returned by getStatsStruct().
+ * The underlying CData handle is freed on destruction.
+ *
+ * @see ZVec::getStatsStruct()
+ */
 class ZVecCollectionStats
 {
     private FFI\CData $handle;

src/ZVecDoc.php

@@ -8,6 +8,18 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Document representation with fluent setters and typed getters.
+ *
+ * Supports typed setters/getters for all scalar, vector, array, and
+ * binary field types. Additional features: operator tracking (OP_INSERT,
+ * OP_UPDATE, OP_UPSERT, OP_DELETE), field nullability, serialization/
+ * deserialization, merge semantics, and memory usage introspection.
+ * Created with `new ZVecDoc('primary_key')` or obtained from query results.
+ *
+ * @see ZVec::insert()
+ * @see ZVec::fetch()
+ */
 class ZVecDoc
 {
     private FFI\CData $handle;

src/ZVecException.php

@@ -9,6 +9,16 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Exception thrown by all ZVec operations on FFI error.
+ *
+ * Carries the C library error code and message. The `$code` maps
+ * directly to the zvec C++ status code; message is the FFI string.
+ * Provides additional error context via getErrorFile(), getErrorLine(),
+ * and getErrorFunction() when verboseErrors is enabled.
+ *
+ * @see ZVec::checkStatus() For the FFI status check pattern
+ */
 class ZVecException extends RuntimeException
 {
     private ?string $errorFile = null;

src/ZVecFieldSchema.php

@@ -8,6 +8,16 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Field schema introspection result.
+ *
+ * Returned by getFieldSchema(). Provides data type, dimension,
+ * vector-specific metadata (dense vs sparse), index type, and
+ * nullability for any collection field. The underlying CData
+ * handle is freed on destruction.
+ *
+ * @see ZVec::getFieldSchema()
+ */
 class ZVecFieldSchema
 {
     private FFI\CData $handle;

src/ZVecGroupByVectorQuery.php

@@ -8,6 +8,18 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Group-by query builder for vector search.
+ *
+ * Groups results by a field value. Supports setting group count,
+ * group top-k, radius, linear mode, and filter expressions.
+ * Currently limited to single-group queries (no multi-group support).
+ * Some query parameter setters (HNSW, IVF, Vamana, Flat) throw
+ * ZVecException as they are not supported for group-by queries.
+ *
+ * @see ZVecVectorQuery
+ * @see ZVec::groupByQuery()
+ */
 class ZVecGroupByVectorQuery implements ZVecQueryInterface
 {
     private FFI\CData $handle;

src/ZVecIndexParams.php

@@ -8,6 +8,17 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Index creation parameter builder.
+ *
+ * Replaces the deprecated createHnswIndex(), createFlatIndex(),
+ * createIvfIndex(), and createHnswRabitqIndex() methods with a
+ * unified, type-safe API. Use factory methods: forHnsw(), forFlat(),
+ * forIvf(), forVamana(), forHnswRabitq(), or forInvert().
+ * The underlying CData handle is freed on destruction.
+ *
+ * @see ZVec::createIndex()
+ */
 class ZVecIndexParams
 {
     private FFI\CData $handle;

src/ZVecQueryInterface.php

@@ -8,6 +8,15 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Common interface for vector query objects.
+ *
+ * Implemented by ZVecVectorQuery and ZVecGroupByVectorQuery.
+ * Provides getHandle() for FFI access and free() for resource cleanup.
+ *
+ * @see ZVecVectorQuery
+ * @see ZVecGroupByVectorQuery
+ */
 interface ZVecQueryInterface
 {
     public function getHandle(): FFI\CData;

src/ZVecReRanker.php

@@ -8,13 +8,13 @@
 
 /**
  * Interface for rerankers that post-process vector search results.
- * 
- * Rerankers are used for:
- * - Multi-vector fusion (combining results from multiple vector fields)
- * - Two-stage retrieval (recall top-K, then rerank to top-N)
- * - Semantic reranking with external models
- * 
- * Implementations: ZVecRrfReRanker, ZVecWeightedReRanker
+ *
+ * Supports multi-vector fusion (combining results from multiple vector
+ * fields), two-stage retrieval (recall top-K then rerank to top-N), and
+ * semantic reranking with external models.
+ *
+ * @see ZVecRrfReRanker
+ * @see ZVecWeightedReRanker
  */
 interface ZVecReRanker
 {

src/ZVecRerankedDoc.php

@@ -6,6 +6,18 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Reranked document wrapper with combined score.
+ *
+ * Returned by reranker implementations (ZVecRrfReRanker,
+ * ZVecWeightedReRanker). Wraps the original ZVecDoc and adds
+ * combinedScore, sourceRanks (per-field rank), and sourceScores
+ * (per-field original score) from multi-vector queries.
+ *
+ * @see ZVecReRanker
+ * @see ZVecRrfReRanker
+ * @see ZVecWeightedReRanker
+ */
 class ZVecRerankedDoc
 {
     private ZVecDoc $doc;

src/ZVecRrfReRanker.php

@@ -9,6 +9,17 @@
 require_once __DIR__ . '/ZVecReRanker.php';
 require_once __DIR__ . '/ZVecRerankedDoc.php';
 
+/**
+ * Reciprocal Rank Fusion (RRF) reranker.
+ *
+ * Combines results from multiple vector field queries using the RRF
+ * scoring formula: score = sum(1 / (rankConstant + rank)) for each
+ * document across all fields. Supports a configurable rank constant
+ * (default: 60) and top-N results limit.
+ *
+ * @see ZVecWeightedReRanker For weighted fusion
+ * @see ZVecReRanker Interface
+ */
 class ZVecRrfReRanker implements ZVecReRanker
 {
     private int $topn;

src/ZVecSchema.php

@@ -8,6 +8,19 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Fluent schema builder for collection field definitions.
+ *
+ * Create with `new ZVecSchema('collection_name')`, then chain add*()
+ * methods to define fields. Minimum requirement: one vector field + one
+ * string field (primary key). Supports scalar types, vector types (FP32,
+ * FP64, INT8, FP16, INT4, INT16, BINARY32, BINARY64), sparse vectors,
+ * array types, and binary fields. The underlying CData handle is freed
+ * on destruction.
+ *
+ * @see ZVec::create()
+ * @see ZVecDoc
+ */
 class ZVecSchema
 {
     private FFI\CData $handle;

src/ZVecVectorQuery.php

@@ -8,6 +8,18 @@
 
 if (extension_loaded('zvec')) return;
 
+/**
+ * Query builder for vector search.
+ *
+ * Supports search parameters (HNSW ef, IVF nprobe, radius, linear mode),
+ * reranking via ZVecReRanker, and filter expressions. Create via constructor
+ * with field name and query vector, or use fromId() for document-based queries.
+ * Return type of ZVec::query() differs when a reranker is attached.
+ *
+ * @see ZVec::query()
+ * @see ZVecGroupByVectorQuery For grouped queries
+ * @see ZVecReRanker
+ */
 class ZVecVectorQuery implements ZVecQueryInterface
 {
     private FFI\CData $handle;

src/ZVecWeightedReRanker.php

@@ -10,6 +10,17 @@
 require_once __DIR__ . '/ZVecReRanker.php';
 require_once __DIR__ . '/ZVecRerankedDoc.php';
 
+/**
+ * Weighted score fusion reranker.
+ *
+ * Combines results from multiple vector field queries using normalized
+ * weighted scores. Supports both METRIC_IP and METRIC_L2 normalisation.
+ * Each field has a configurable weight; scores are normalised to [0,1]
+ * per field before fusion.
+ *
+ * @see ZVecRrfReRanker For rank-based fusion
+ * @see ZVecReRanker Interface
+ */
 class ZVecWeightedReRanker implements ZVecReRanker
 {
     private int $topn;