Jérôme Bousquié
45 lines
3.0 KiB
Markdown
45 lines
3.0 KiB
Markdown
---
|
|
type: Reference
|
|
title: IAgent Documentation Rules
|
|
description: Rules and guidelines for documentation in the IAgent project, following OKF v0.2 specification
|
|
tags: [documentation, guidelines, standards]
|
|
status: stable
|
|
generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
|
|
---
|
|
|
|
# IAgent Documentation Rules
|
|
|
|
## Language
|
|
|
|
All documentation is written in English; as a convention, the code itself uses English for variable names, function names, etc.
|
|
|
|
## Code Documentation
|
|
|
|
Every source file and configuration file must be systematically documented following the rules defined in this DOCUMENTATION.md file. Additionally, every directory must contain its own README.md file summarizing and explaining the module's organization at that level: what is the overall responsibility of the files grouped in this directory, which ones they are, and what each one does.
|
|
|
|
We assume the reader has professional algorithmic knowledge but may not necessarily be a Rust specialist. The reader does know the project's domain — LLM logic, clients, and agents. Documentation should therefore be tailored for a professional developer who knows some programming languages (not necessarily Rust).
|
|
|
|
### General Rule
|
|
|
|
Documentation must describe what is coded and what purpose it serves. A LLM reading the code and documentation should be able to verify whether:
|
|
- the documentation correctly describes what the code does,
|
|
- the code doesn't do something other than what the documentation says.
|
|
|
|
### File Headers
|
|
|
|
Each module or file must include documentation explaining the module's responsibility and how it interacts with other modules in the program, at least those within its own directory. This documentation must detail the main objects (Struct, Enum, Trait) manipulated in the module and the primary functions that carry the module's core logic.
|
|
|
|
## Within a File's Code
|
|
|
|
### Object and Function Headers
|
|
|
|
At the header of each object, describe what the object represents and its purpose. At the header of each function, describe what the function does, what inputs it expects, and what it returns. Also describe when or by whom it is typically called. This part of the description should fit within three lines maximum. If the function body exceeds fifteen lines of code, also add its internal steps and how it accomplishes them, in three lines maximum. If the function has points of attention or complex technical resolutions (such as a specific Rust idiom or library trick for solving an ownership or lifetime problem), these are documented after the function header in up to three lines of explanation.
|
|
|
|
### In the Code Body
|
|
|
|
If an object or function presents a particularity or specific technical point, then a descriptive comment is inserted directly into the code body or function body. If a point of attention or technical point was described in the function header, then a comment in the code body reminds where this point is located.
|
|
|
|
## Documentation Maintenance
|
|
|
|
The rules defined in this file are regularly applied across all code documentation to ensure consistency between code evolution and its documentation.
|