docs: improve docstrings for API reference (#612) by planetf1 · Pull Request #614 · generative-computing/mellea

planetf1 · 2026-03-10T23:02:45Z

Misc PR

Type of PR

Bug Fix
New Feature
Documentation
Other

Description

Link to Issue: Fixes docs: improve module-level docstrings for API reference #612, Fixes docs: add Args/Returns sections to public function docstrings #613

Fixes #612, Fixes #613

Comprehensive docstring quality pass across the entire mellea and cli codebase, covering four areas. Note that during implementation additional gaps were identified beyond those listed in the original issues and fixed in the same pass.

This PR is independent of #611 (the API doc pipeline tooling) and can be merged without it.

Module-level docstrings (#612)
Expands module-level docstrings across 53 files covering all three priority tiers from the issue: __init__.py landing pages (P1), modules with no docstring at all (P2), and one-liner stubs that merely restated the module name (P3). Each docstring now describes the module's purpose, its key exports, and when to reach for it.

Google-style Args/Returns/Raises (#613)
Adds missing Args:, Returns:, and Raises: sections to public functions and methods across all modules. Also converts RST-style :param:/:returns: docstrings (inherited from upstream granite_io) to Google style to match the project convention (pyproject.toml convention = "google").

Attributes: sections on class docstrings (#613)
Adds or expands Attributes: sections on class docstrings across core, backends, formatters, stdlib, and cli, covering classes such as RESTHandler, JsonFormatter, FancyLogger, SimpleLRUCache, SubscriptableBaseModel, TableQuery, TableTransform, GenerativeSlot, Query, Transform, BudgetForcingSamplingStrategy, and others.

Class-level Args: sections (#613)
Adds Args: sections to class docstrings that had Attributes: but no Args:, covering 19 classes — including dataclasses whose __init__ is auto-generated from field annotations. Several of these were identified during review rather than appearing in the original issue report.

Testing

Tests added to the respective file if code was changed
New code has 100% coverage if code as added
Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

github-actions · 2026-03-10T23:02:55Z

The PR description has been updated. Please fill out the template for your PR to be reviewed.

mergify · 2026-03-10T23:03:23Z

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert|release)(?:\(.+\))?:

TASK.md

jakelorocco

I think this seems reasonable. I tried to look at very important parts of the code base (ie core) and the changes seemed reasonable.

We should remove the attributes from the docstring and move any attribute descriptions we want to be docstrings on those fields. At least for me, having both attributes and args causes confusing output in VSCode:

Docstrings directly on the fields also allows for detailed descriptions when hovering them.

def __init__(f1: int):
  self.f1 = f1
  """field 1"""

…mputing#612) Replace one-liner and missing module docstrings across 53 files with substantive 2-4 sentence descriptions covering each module's purpose, key exports, and when to reach for it. Covers all three priority tiers from the issue: __init__.py landing pages, undocumented modules, and short stubs that merely restated the module name.

…omputing#613) Add missing ``Args:`` and ``Returns:`` sections to all public functions and methods across ``mellea/`` and ``cli/`` that lacked them. Also converts RST-style ``:param:``/``:returns:`` docstrings inherited from the ``granite_io`` upstream into Google style to match the project convention (``pyproject.toml`` ``convention = "google"``). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…computing#613) Add or expand Google-style docstrings across CLI and library modules: - cli/alora/train.py: add docstrings to load_dataset_from_json, formatting_prompts_func, SaveBestModelCallback, SafeSaveTrainer, train_model - cli/decompose/decompose.py: add class docstring to DecompVersion, expand run() with full Args section - cli/decompose/pipeline.py: add class docstrings to ConstraintResult, DecompSubtasksResult, DecompPipelineResult, DecompBackend; add full docstring with Args/Returns to decompose() - cli/decompose/utils.py: add Args/Returns to validate_filename - cli/eval/commands.py: add full docstring with Args to eval_run - cli/m.py: expand callback docstring - mellea/backends/adapters/adapter.py: expand LocalHFAdapter docstring - mellea/backends/cache.py: expand SimpleLRUCache docstring - mellea/backends/tools.py: expand SubscriptableBaseModel docstring; fix json_extraction to use Returns: instead of Yields: - mellea/core/backend.py: expand Backend docstring; add Args/Returns to generate_walk - mellea/core/base.py: add Args/Returns to blockify and get_images_from_component - mellea/core/utils.py: expand RESTHandler, JsonFormatter, FancyLogger class docstrings - mellea/helpers/openai_compatible_helpers.py: add Args/Returns to message_to_openai_message and messages_to_docs - mellea/stdlib/components/docs/richdocument.py: expand TableQuery and TableTransform class docstrings - mellea/stdlib/components/genslot.py: expand Argument, Function, Arguments, GenerativeSlot class docstrings; add SyncGenerativeSlot class docstring - mellea/stdlib/components/mobject.py: expand Query and Transform class docstrings - mellea/stdlib/requirements/requirement.py: add Args sections to req() and check() - mellea/stdlib/sampling/budget_forcing.py: expand BudgetForcingSamplingStrategy class docstring Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…e-computing#613) Add Args: sections to class docstrings that had Attributes: but no Args:, completing Google-style docstring coverage: - core/requirement.py: ValidationResult, Requirement - core/sampling.py: SamplingResult - core/base.py: CBlock, ImageBlock, ModelOutputThunk, ContextTurn, TemplateRepresentation, GenerateLog, ModelToolCall - formatters/template_formatter.py: TemplateFormatter - formatters/granite/intrinsics/input.py: IntrinsicsRewriter - formatters/granite/intrinsics/output.py: TransformationRule, TokenToFloat, DecodeSentences, MergeSpans - formatters/granite/retrievers/embeddings.py: InMemoryRetriever - stdlib/components/chat.py: Message, ToolMessage - helpers/async_helpers.py: ClientCache

planetf1 · 2026-03-12T11:40:46Z

Thanks for the feedback @jakelorocco — glad the core changes look ok!

Agree — I see this with Pylance too. The hover output is confusing. I looked at a few instances:

Pylance merges Args: and Attributes: under a single "Args" heading — by design, not a bug
In CBlock: cache and value appear twice with near-identical descriptions — noise
In ReactInitiator: goal appears twice with different types (str in Args, CBlock in Attributes) — looks contradictory even though both are correct

Attributes: is required by the Google Python Style Guide §3.8.4, enforced by ruff convention = "google", and parsed by the docs tooling — so switching to inline post-assignment strings isn't really an option without more impacts. However the guide's example shows the same field in both sections with complementary wording: Args: for the input, Attributes: for the stored state.

So I've dropped the redundant Attributes: entries from the classes touched here (CBlock, ImageBlock, ModelOutputThunk, ContextTurn, FormatterBackend, and a couple of CLI classes), keeping only entries that add something new — e.g. the computed properties on TestEvalResult.

Happy to raise a follow-on issue if there are more cases elsewhere.

…ve-computing#613) Remove Attributes: sections where fields duplicate constructor params verbatim (same name, same type, same description), keeping only entries that add genuinely new information (computed/derived attributes): - mellea/backends/backend.py: FormatterBackend - mellea/core/base.py: CBlock, ImageBlock, ModelOutputThunk, ContextTurn - cli/eval/runner.py: InputEvalResult, TestEvalResult (keep computed properties passed_count, total_count, pass_rate) Also removes TASK.md left over from development. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

planetf1 · 2026-03-12T11:49:53Z

Changes made, but check failing with some type checking errors from cpex:


mellea/plugins/policies.py:8: error: Cannot find implementation or library stub for module named "cpex.framework.hooks.policies"  [import-not-found]
mellea/plugins/context.py:8: error: Cannot find implementation or library stub for module named "cpex.framework.models"  [import-not-found]
mellea/plugins/types.py:9: error: Cannot find implementation or library stub for module named "cpex.framework.hooks.registry"  [import-not-found]
mellea/plugins/types.py:10: error: Cannot find implementation or library stub for module named "cpex.framework.models"  [import-not-found]
mellea/plugins/base.py:106: error: Cannot find implementation or library stub for module named "cpex.framework.base"  [import-not-found]
mellea/plugins/base.py:106: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
mellea/plugins/base.py:107: error: Cannot find implementation or library stub for module named "cpex.framework.models"  [import-not-found]
mellea/plugins/manager.py:14: error: Cannot find implementation or library stub for module named "cpex.framework.manager"  [import-not-found]
mellea/plugins/registry.py:16: error: Cannot find implementation or library stub for module named "cpex.framework.base"  [import-not-found]
mellea/plugins/registry.py:17: error: Cannot find implementation or library stub for module named "cpex.framework.models"  [import-not-found]
Installing missing stub packages:
/home/runner/work/mellea/mellea/.venv/bin/python3 -m pip install lxml-stubs pandas-stubs scipy-stubs types-PySocks types-PyYAML types-Pygments types-cachetools types-colorama types-decorator types-defusedxml types-geopandas types-greenlet types-grpcio types-html5lib types-jsonschema types-networkx types-objgraph types-openpyxl types-pexpect types-protobuf types-psutil types-pycurl types-python-dateutil types-pywin32 types-regex types-reportlab types-setuptools types-simplejson types-tabulate types-tensorflow types-ujson types-xlrd types-xmltodict types-yt-dlp


Found 9 errors in 6 files (checked 443 source files)

Will look at how to address... maybe bad in main?

mypy 1.18.2 reports import-not-found for cpex.framework.* (which has no py.typed marker). 1.19.1 handles this correctly and was the version used when PR generative-computing#582 passed CI. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

planetf1 · 2026-03-12T12:23:21Z

Build failure caused by regressed uv.lock from resolving merge conflict. Updated/pushed

jakelorocco · 2026-03-12T15:53:18Z

Attributes: is required by the Google Python Style Guide §3.8.4, enforced by ruff convention = "google", and parsed by the docs tooling — so switching to inline post-assignment strings isn't really an option without more impacts. However the guide's example shows the same field in both sections with complementary wording: Args: for the input, Attributes: for the stored state.

@planetf1, looking at the style guide, it looks like Attributes and Args serve different purposes. Attributes are in class docstrings while Args are in function docstrings. I think this line is somewhat blurred because (VSCode at least) rarely shows the class docstring. I think we should:

keep init functions only showing the args
replace class docstrings to have attributes

if we want to maintain attributes in the docstring.

cli/decompose/pipeline.py

planetf1 · 2026-03-13T14:03:31Z

will revisit content/attribute discussion once pipeline pr progressed - there is some relationship in parsing/validation.

planetf1 marked this pull request as ready for review March 10, 2026 23:05

planetf1 requested review from a team, jakelorocco and nrfulton as code owners March 10, 2026 23:05

This was referenced Mar 11, 2026

ci: gate doc quality in CI and pre-commit to prevent future degradation #616

Open

docs: Docs/api pipeline improvements #611

Merged

docs: implement publishing pipeline #617

Closed

planetf1 requested review from HendrikStrobelt and psschwei March 11, 2026 11:23

planetf1 changed the title ~~docs: expand module-level docstrings for API reference (#612)~~ docs: improve docstrings for API reference (#612) Mar 11, 2026

planetf1 added the documentation Improvements or additions to documentation label Mar 11, 2026

psschwei reviewed Mar 11, 2026

View reviewed changes

TASK.md Outdated Show resolved Hide resolved

jakelorocco reviewed Mar 11, 2026

View reviewed changes

planetf1 and others added 5 commits March 12, 2026 11:32

fix: replace EN DASH with hyphen in docstrings (RUF002)

67febce

planetf1 force-pushed the improvedocstrings branch from b05ea2c to 0a0bcc7 Compare March 12, 2026 11:44

planetf1 enabled auto-merge March 12, 2026 12:23

AngeloDanducci reviewed Mar 13, 2026

View reviewed changes

cli/decompose/pipeline.py Show resolved Hide resolved

planetf1 mentioned this pull request Mar 13, 2026

docs: implement publishing pipeline (#617) #644

Closed

8 tasks

planetf1 mentioned this pull request Mar 13, 2026

docs: implement publishing pipeline (#617) #646

Merged

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: improve docstrings for API reference (#612)#614

docs: improve docstrings for API reference (#612)#614
planetf1 wants to merge 7 commits intogenerative-computing:mainfrom
planetf1:improvedocstrings

planetf1 commented Mar 10, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 10, 2026

Uh oh!

mergify bot commented Mar 10, 2026

Uh oh!

Uh oh!

jakelorocco left a comment

Uh oh!

planetf1 commented Mar 12, 2026 •

edited

Loading

Uh oh!

planetf1 commented Mar 12, 2026

Uh oh!

planetf1 commented Mar 12, 2026

Uh oh!

jakelorocco commented Mar 12, 2026

Uh oh!

Uh oh!

planetf1 commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

planetf1 commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Misc PR

Type of PR

Description

Testing

Uh oh!

github-actions bot commented Mar 10, 2026

Uh oh!

mergify bot commented Mar 10, 2026

Merge Protections

🟢 Enforce conventional commit

Uh oh!

Uh oh!

jakelorocco left a comment

Choose a reason for hiding this comment

Uh oh!

planetf1 commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

planetf1 commented Mar 12, 2026

Uh oh!

planetf1 commented Mar 12, 2026

Uh oh!

jakelorocco commented Mar 12, 2026

Uh oh!

Uh oh!

planetf1 commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

planetf1 commented Mar 10, 2026 •

edited

Loading

planetf1 commented Mar 12, 2026 •

edited

Loading