docs: package-wide docstring standardization - #488
Draft
lkdvos wants to merge 4 commits into
Draft
Conversation
Write down the conventions the package-wide docstring pass applies: section headings, `- name::Type: description` argument lists, cross-linking with `@ref` / `@extref`, `@cite` references, and how algorithm types document their fields and constructors. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`SketchedExpand`'s docstring cites the controlled-bond-expansion paper, so add the corresponding bibliography entry. Rename the one capitalised citation key to `hubig2015` for consistency with every other key in the file, and update the `@cite` in `DMRG3S` to match. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Prose and formatting pass over every docstring in `src/`, following `docs/DOCSTRING_STYLE.md`: - unify bullet markers on `-` and argument lists on `- name::Type: description` - promote `##` section headings to `#`, and order them consistently (signature, description, arguments, keywords, returns, examples, see-also, references) - switch algorithm types to `$(TYPEDEF)`/`$(TYPEDFIELDS)` with per-field docstrings, and document their constructors under `# Constructors` - add `Used as the ... argument of [...](@ref)` cross-links so algorithm types point back at the driver they plug into - link upstream API with `[text](@extref Pkg.name)` (KrylovKit, MatrixAlgebraKit, TensorOperations) instead of naming it in plain text - normalise spacing in type parameters and keyword defaults (`PeriodicArray{T,1}` -> `PeriodicArray{T, 1}`, `side=:both` -> `side = :both`) - add `@cite` references where an algorithm has a canonical paper - new or substantially expanded docstrings for the quasiparticle state types, the finite environment types, and several driver functions, with runnable `jldoctest` examples on the main entry points Also drop a link to a non-existent `entanglement_spectrum` anchor in `entanglementplot`, retargeting it at the `entanglement_spectrum` docstring. This commit changes documentation only. Verified by stripping docstrings, comments and blank lines from both `origin/main`'s version and this one of every touched file and diffing the results, which is empty. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests.
🚀 New features to boost your workflow:
|
Contributor
|
After the build completes, the updated documentation will be available here |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docstring standardization slice of #449, re-applied on top of current
main: a newdocs/DOCSTRING_STYLE.mdand its conventions applied to 53 files undersrc/— unified bullets and argument lists, a fixed section order,$(TYPEDEF)/$(TYPEDFIELDS)for algorithm structs,@extreflinks to upstream APIs, driver ↔ algorithm cross-links, and runnablejldoctestexamples on the main entry points.Documentation-only. Stripping docstrings and comments from every touched
src/file and diffing againstmaingives an empty result — no code changed. The three genuine code changes hiding in #449'ssrc/diff went to #489 instead.Two things beyond the style pass:
src/utility/plotting.jllinked(@ref entanglement_spectrum), an anchor that exists nowhere; sincelib/lib.mdautodocs the whole module, this fails the build. Retargeted at the realentanglement_spectrumdocstring.trschemebytrunc#482 (trscheme→trunc) and Refactor MPSTensor construction to fix type piracy #475 (removedMPSTensorconstructors), so it was applied as a patch keepingmain's code; the affected docstrings and onejldoctestwere rewritten accordingly.Also adds two
mpskit.biblines these docstrings need: thegleis2023entry, and theHubig2015→hubig2015rename with its@cite. Expect a one-line conflict with #487 on that key; take lowercase.Doctests pass and the Documenter half of the build is clean; the
vitepress buildstep can't run on my machine (host glibc too old for rollup), so CI should confirm the HTML render.🤖 Generated with Claude Code