Add JSDoc and README API reference

[Just-Bamford]

Summary

The @anonvote/crypto SDK has no documentation. Each function lacks JSDoc comments, there is no README with examples, and developers have no way to understand the API without reading source code. Complete documentation is required before publishing to npm.

This is a Milestone 3 requirement. Documentation is part of a professional SDK release.

Background

The crypto module exports five primitives but they are not documented. There is no README in the js/ folder. There are no code examples. New developers cannot discover the API or understand what each function does.

Scope

JSDoc Comments

• Add JSDoc comments to all exported functions and classes:
  • hashIdentifier
  • encryptVote
  • decryptVote
  • verifyVoteHash
  • generateBallotKey
  • AnonVoteClient (see issue Implement the AnonVoteClient SDK for creating elections and casting votes #8)
• Each comment should include:
  • Brief description
  • @param for each parameter with type and description
  • @returns with return type and description
  • @throws for any errors thrown
  • @example with a code snippet

README

• Create js/README.md with:
  • Project description
  • Installation instructions
  • Quick start example
  • API reference (link to or embed JSDoc)
  • Contributing guidelines
  • License

Type Definitions

• Ensure TypeScript types are exported and correct
• No any types — all functions should be fully typed

Tests

• Documentation builds without errors (if using typedoc)
• Examples in JSDoc are syntactically correct
• All functions mentioned in README have corresponding JSDoc

Relevant Files

• js/src/crypto/index.ts
• js/src/crypto/encrypt.ts
• js/src/crypto/hash.ts
• js/src/crypto/verify.ts
• js/src/client/AnonVoteClient.ts
• js/README.md (new)

Acceptance Criteria

• All functions have JSDoc comments
• README provides quick start and API reference
• All TypeScript types are correct and exported
• Examples in documentation are runnable

Out of Scope

• Full API documentation site — README and JSDoc are sufficient
• Internationalized documentation — English only
• Video tutorials — written docs only

Note for Contributors

Use typedoc comments sparingly — keep examples short and focused. Link to the full AnonVote documentation for deeper context. Make sure examples match the actual function signatures.

[Luchistack]

I would love to work on this issue.

[heymide]

I'm excited to contribute to this milestone because comprehensive documentation is essential for a successful SDK release and a great developer experience.

My approach is to document every public API in the @anonvote/crypto package with clear, consistent JSDoc comments, including parameter descriptions, return values, thrown errors, and practical usage examples. I'll ensure each example is syntactically correct, reflects real-world usage, and stays aligned with the implementation.

In addition, I'll create a comprehensive js/README.md covering the project's purpose, installation, quick start guide, API overview, contribution guidelines, and licensing. I'll also verify that all TypeScript types are explicitly defined and exported, avoiding any types while ensuring the documentation accurately reflects the SDK's public interface.

Finally, I'll validate that all examples are runnable, confirm that every documented function has corresponding JSDoc comments, and ensure the package is well-prepared for publication with documentation that makes it easy for developers to adopt and integrate the SDK.

With experience building TypeScript libraries and writing developer-focused documentation, I'm confident I can deliver clear, maintainable, and production-ready documentation that meets the project's acceptance criteria.

[grantfox-oss]

🦊 GrantFox — @heymide has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #23)
2. Your PR will be reviewed by the AnonVote maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🦊 GrantFox — @heymide has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #23)
2. Your PR will be reviewed by the AnonVote maintainers

Good luck! Track your progress on GrantFox.