Skip to content

docs: add Javadoc to datastore core interfaces #546

Description

@ginccc

Summary

The datastore package defines the storage abstraction layer that ALL config stores extend. These are the most important interfaces to document because they define the versioned CRUD contract used throughout the entire project.

Interfaces to document (7)

  • src/main/java/ai/labs/eddi/datastore/IResourceFilter.java
  • src/main/java/ai/labs/eddi/datastore/IResourceStorage.java
  • src/main/java/ai/labs/eddi/datastore/IResourceStorageFactory.java
  • src/main/java/ai/labs/eddi/datastore/IResourceStore.java
  • src/main/java/ai/labs/eddi/datastore/serialization/IDescriptorStore.java
  • src/main/java/ai/labs/eddi/datastore/serialization/IDocumentBuilder.java
  • src/main/java/ai/labs/eddi/datastore/serialization/IJsonSerialization.java

How to write good Javadoc

  1. Read the implementation class to understand what the interface does
  2. Look at the model class it operates on
  3. Write 2-3 lines: purpose + what consumes it + key behaviors

Good example (see IConversationMemoryStore):

/**
 * Persistence store for conversation memory snapshots.
 * Called by the lifecycle pipeline to save/load conversation state
 * between turns and across server restarts.
 */

Bad example (don't do this):

/** Store for agents. */

Note: If the interface currently has only /** @author ginccc */, replace it with
meaningful Javadoc. Per CONTRIBUTING.md, @author tags are not used in new code.

Tips

  • IResourceStore is the root interface — start here. All config stores extend it.
  • Look at AbstractResourceStore to understand the versioning and CRUD lifecycle.
  • IResourceStorage vs IResourceStore: storage is the low-level DB access, store is the higher-level versioned API. Document this distinction.

Acceptance criteria

  • All 7 interfaces have class-level Javadoc
  • IResourceStore Javadoc explains the versioning contract
  • Any existing @author tags are removed
  • ./mvnw compile passes

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationJavadoc, markdown docs, OpenAPI annotations, code commentsgood first issueClear scope, low risk, pattern to follow - ideal for newcomershelp wantedsize: SSmall: about 1 hour, 2-8 files, mechanical pattern-following

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions