Documentation Requirements for Developers

To ensure high quality and consistency of documentation in the Nrgy.js project, all developers must follow these rules when adding or changing functionality.

General Rules

1. Documentation Placement: Source code documentation files should be placed in the same folder as the source file itself.

• Example: packages/core/src/reactivity.ts -> packages/core/src/reactivity.md.

2. Localization: Documentation must be translated into English and Russian. AI translation is acceptable.

• The translation should be placed in a separate file with the locale as a suffix.
• Example: packages/core/src/reactivity.ru.md.

3. Format: Documentation is written in Markdown format.

4. No index.ts File Articles: Do not create standalone documentation files for index.ts source files.

• Public package entry points such as index.ts must be documented in the package-level README.md or other package-level documentation instead.

Article Structure for a File (Module)

Each article should contain the following sections:

1. Purpose: A brief description of what problem the file/module solves.
2. Overview: A more detailed description of the logic and context of use.
3. Conceptual Architecture: Description of internal mechanisms and relationships with other parts of the system.
4. Public API Description: A list of exported functions, classes, and types with descriptions of parameters and return values.
5. Usage Examples: Practical code examples (Code Blocks) demonstrating API usage.

Article Structure for a Package

Each package should have a README.md file in its root (usually next to index.ts or in the root of the package folder) or an index.md file in the general docs folder, containing:

1. Package Purpose: Why this package is needed.
2. Overview: Main ideas and principles.
3. Package Installation: Commands for installation (npm/yarn/pnpm).
4. Conceptual Architecture: How the package is organized internally.
5. Feature Documentation: Links to key modules or a summary description.
6. Usage Examples: Integration examples.

Writing Style

• Use clear and concise technical language.
• Code in examples must be functional and follow project standards.
• Use inline code formatting for API function and parameter names.
• Keep terminology consistent: Atom, Effect, Scope, Controller, View Model.
• Use level-2 (##) section headers.

Prompt Template for Documentation Agents

When using an AI agent to generate documentation for a TypeScript source file, apply the following task framing. The agent already has direct file access, so no / placeholders are needed — point it at the file and rely on the rules above.

Task: Analyze the given TypeScript source file and produce documentation for it in Markdown.

Rules:

1. Place the new doc next to the source file with the same basename and a .md extension. Do not generate a standalone doc for index.ts; document entry points in the package README.md instead.
2. Produce a Russian translation in a sibling .ru.md file.
3. Include the five sections listed in Article Structure for a File (Module): Purpose, Overview, Conceptual Architecture, Public API Description, Usage Examples.
4. Examples must be valid TypeScript that compiles conceptually against the current public API. Use the consistent terminology listed above.