Skip to content

Fix three more docstrings that name parameters the functions do not have - #2409

Merged
ricardoV94 merged 1 commit into
pymc-devs:mainfrom
VenishPaneliya:docstring-param-names-2
Sep 8, 2026
Merged

Fix three more docstrings that name parameters the functions do not have#2409
ricardoV94 merged 1 commit into
pymc-devs:mainfrom
VenishPaneliya:docstring-param-names-2

Conversation

@VenishPaneliya

Copy link
Copy Markdown
Contributor

Description

Follow-up to #2408 — same class of mismatch, three more sites. Docs only, no code touched.

FunctionGraph.import_var takes var but documents variable:

def import_var(
    self, var: Variable, reason: str | None = None, import_missing: bool = False
) -> None:

replace_patterns (d3viz) takes x but documents s. Its own summary line already refers to the argument correctly — "Replace replace in string x" — so the Parameters entry is the odd one out.

toposort_with_orderings is the one I asked about on #2408, and I think the evidence now settles it. The signature is:

def toposort_with_orderings(
    graphs: Iterable[Variable],
    *,
    blockers: Iterable[Variable] | None = None,
    orderings: dict[Apply, list[Apply]] | None = None,
) -> Generator[Apply, None, None]:

but the Parameters section documents graphs, outputs and orderingsoutputs isn't a parameter, and blockers is missing. The remaining graphs entry was also backwards, describing it as "Graph inputs". Two summary lines say the opposite:

  • this function's own: "Perform topological of nodes between blocker (input) and graphs (output) variables ..."
  • toposort, which it delegates to for the no-orderings branch: "Topologically sort of Apply nodes between graphs (outputs) and blockers (inputs)."

and the implementation agrees — the # the inputs are used to decide where to stop expanding comment sits directly above if blockers:. So graphs are the outputs and blockers are the inputs, and the entry that said outputs was describing blockers under the wrong name.

I've made it:

    graphs : list or tuple of Variable instances
        Graph outputs.
    blockers : list or tuple of Variable instances
        Graph inputs.

If you'd rather I'd left that one alone, or you read the roles differently, say so and I'll drop it from this PR — the other two stand on their own.

Related Issue

Checklist

  • Checked that the pre-commit linting/style checks pass — ruff check clean on all three files
  • Included tests that prove the fix is effective — not applicable, docstring text only
  • Added necessary documentation (docstrings and/or example notebooks)

Type of change

  • Documentation

Follow-up to pymc-devs#2408, same class of mismatch.

`FunctionGraph.import_var` takes `var` but documents `variable`.

`replace_patterns` takes `x` but documents `s`; its own summary line
already says "Replace `replace` in string `x`".

`toposort_with_orderings` documents `outputs`, which is not a parameter,
and leaves `blockers` undocumented. It also had the remaining entry
backwards: `graphs` was described as "Graph inputs". Both summary lines
say otherwise - this function's own reads "between blocker (input) and
graphs (output) variables", and `toposort`, which it delegates to, says
"between graphs (outputs) and blockers (inputs)".
@ricardoV94 ricardoV94 added the docs label Sep 8, 2026
@ricardoV94
ricardoV94 merged commit 44373b4 into pymc-devs:main Sep 8, 2026
67 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants