| single |
# Annotated Doc
Document parameters, class attributes, return types, and variables inline,
with `Annotated`.
[image]
[image]
[image]
[image]
## Installation
```bash
pip install annotated-doc
```
Or with `uv`:
```Python
uv add annotated-doc
```
## Usage
Import `Doc` and pass a single literal string with the documentation for
the specific parameter, class attribute, return type, or variable.
For example, to document a parameter `name` in a function `hi` you could
do:
```Python
from typing import Annotated
from annotated_doc import Doc
def hi(name: Annotated[str, Doc("Who to say hi to")]) -> None:
print(f"Hi, {name}!")
```
You can also use it to document class attributes:
```Python
from typing import Annotated
from annotated_doc import Doc
class User:
name: Annotated[str, Doc("The user's name")]
age: Annotated[int, Doc("The user's age")]
```
The same way, you could document return types and variables, or anything
that could have a type annotation with `Annotated`.
## Who Uses This
`annotated-doc` was made for:
* [FastAPI]
* [Typer]
* [SQLModel]
* [Asyncer]
`annotated-doc` is supported by [griffe-typingdoc], which powers reference
documentation like the one in the [FastAPI Reference].
## Reasons not to use `annotated-doc`
You are already comfortable with one of the existing docstring formats,
like:
* Sphinx
* numpydoc
* Google
* Keras
Your team is already comfortable using them.
You prefer having the documentation about parameters all together in a
docstring, separated from the code defining them.
You care about a specific set of users, using one specific editor, and that
editor already has support for the specific docstring format you use.
## Reasons to use `annotated-doc`
* No micro-syntax to learn for newcomers, it’s **just Python** syntax.
* **Editing** would be already fully supported by default by any editor
(current or future) supporting Python syntax, including syntax errors,
syntax highlighting, etc.
* **Rendering** would be relatively straightforward to implement by static
tools (tools that don't need runtime execution), as the information can be
extracted from the AST they normally already create.
* **Deduplication of information**: the name of a parameter would be
defined in a single place, not duplicated inside of a docstring.
* **Elimination** of the possibility of having **inconsistencies** when
removing a parameter or class variable and **forgetting to remove** its
|