# Docstring Style Guide (Google Style)

Last updated: 2026-02-25

This project uses **Google-style docstrings** for public APIs and stable
user-facing modules.

## Scope

Prioritize docstrings for:

- root exports (`astrodyn_core`)
- facade clients and public entry points
- typed specs/models used in tutorials/examples
- public helper functions in `orekit_env`, `states`, `mission`, `uncertainty`

De-prioritize initially:

- private helpers
- obvious internal glue code
- autogenerated/boilerplate modules

## Rules

- Document behavior and intent, not syntax that is obvious from the signature.
- Use parameter names exactly as declared.
- State units explicitly (`m`, `km`, `s`, `rad`, UTC, etc.) when applicable.
- Mention Orekit/JVM requirements when relevant.
- Mention side effects (disk writes, generated files, network calls).
- Keep examples short and runnable where possible.
- Do not change code behavior while adding docstrings.

## Google-style template

```python
def func(arg1: int, arg2: str | None = None) -> bool:
    """One-line summary in imperative/behavioral style.

    Optional short paragraph with context, constraints, or important caveats.

    Args:
        arg1: Meaning of the value and any units/constraints.
        arg2: Optional parameter semantics and default behavior.

    Returns:
        What is returned, including structure/units when relevant.

    Raises:
        ValueError: When input validation fails.
        RuntimeError: When an external dependency is unavailable.
    """
```

## Class docstrings

- Describe the role of the class and where it fits in the workflow.
- Document constructor parameters in `__init__` unless using dataclass fields with
  clear field doc comments or external model docs.
- For façade/service classes, include a short "typical usage" example.

## Dataclasses and typed specs

For spec/model classes used in user configuration:

- Explain what subsystem they configure.
- Document units and defaults.
- Note which fields are optional vs required.
- Mention compatibility constraints (for example, "DSST ignores X").

## Examples in docstrings

Allowed for stable public APIs only.

- Keep examples minimal
- Avoid long setup blocks (link to tutorial pages for full workflow)
- Prefer examples that do not require secrets or network access

## Accuracy checklist (for human review)

Before merging LLM-generated docstrings, verify:

- parameter names match the code
- return type/shape/units are correct
- exceptions actually occur
- examples reflect current public API
- no invented behavior or unsupported guarantees
