Subcategory: executable documentation
Current → target: 6 → 9
Problem
There are no runnable examples anywhere in the source. The doc-example checker reports:
"docstrings": { "source_root": "scs", "files": 1, "examples": 0, "locations": [] }
"notes": ["no doctest examples found — docstring coverage says nothing about whether the
docstrings are true, and here there is nothing to check"]
Every public symbol in scs/py/__init__.py carries prose documentation — LinearSolver,
SCS.__init__, SCS.solve, SCS.update — but none of it is executable, so nothing verifies
that what the docstrings claim is still true. This is the failure with the longest half-life
in a library: the docstring keeps rendering perfectly after the behaviour changes underneath it.
Two related gaps in the same file, worth closing at the same time:
- the
SCS class itself (scs/py/__init__.py:87) has no class docstring
- the public legacy
solve() function (scs/py/__init__.py:218) has only a # comment
above it, not a docstring
Files / lines to change
scs/py/__init__.py:186 (SCS.solve), :205 (SCS.update), :218 (legacy solve) —
add >>> examplesscs/py/__init__.py:87 — add a class docstring for SCS- wire
--doctest-modules (or the doc-example checker with --run) into a CI job
Done when
SCS.solve, SCS.update and the legacy solve() each carry a >>> example, and those
doctests are executed by CI rather than only rendered.
Subcategory: executable documentation
Current → target: 6 → 9
Problem
There are no runnable examples anywhere in the source. The doc-example checker reports:
Every public symbol in
scs/py/__init__.pycarries prose documentation —LinearSolver,SCS.__init__,SCS.solve,SCS.update— but none of it is executable, so nothing verifiesthat what the docstrings claim is still true. This is the failure with the longest half-life
in a library: the docstring keeps rendering perfectly after the behaviour changes underneath it.
Two related gaps in the same file, worth closing at the same time:
SCSclass itself (scs/py/__init__.py:87) has no class docstringsolve()function (scs/py/__init__.py:218) has only a#commentabove it, not a docstring
Files / lines to change
scs/py/__init__.py:186(SCS.solve),:205(SCS.update),:218(legacysolve) —add
>>>examplesscs/py/__init__.py:87— add a class docstring forSCS--doctest-modules(or the doc-example checker with--run) into a CI jobDone when
SCS.solve,SCS.updateand the legacysolve()each carry a>>>example, and thosedoctests are executed by CI rather than only rendered.