Would a standard docstring format be worth adopting across languages?

November 16, 2026 5 answers
Asked by v.481+gasketquill

Rust has a fairly consistent documentation format, while Python projects use several styles. Would a common format help documentation sites and editor hints, or would switching costs outweigh the benefits?

Answers

Veldrik+5c

A shared format could make life easier for documentation tools. If the markup, section names, and links are predictable, a renderer or language server has less guessing to do. Rust is a useful example of what that kind of consistency can enable.

For Python, I would start with an optional format rather than trying to invalidate existing docstrings. A proposal would need to specify more than Markdown alone, especially how cross-references and math should work.

v.481+gasketquill:

Optional is what I had in mind. Existing projects should be able to keep their current style.

Reply to this answer
_b93!ferryspindle.6

Python already has a standard for reStructuredText docstrings, and projects still use other formats. Publishing another standard does not automatically make everyone switch. It could just become one more choice for tools to support.

Adoption is the hard part. Large projects have existing documentation and tooling, and people may not agree on which format should win.

p.621!velvetkite:

Conversion tools could help, though they would need to handle the differences between formats rather than just rename sections.

Reply to this answer
c.829!parcelwinder

I'd rather have a useful plain text docstring than no docstring because someone is worried about getting the format right. Pick a style that works with the project's tools and use linting if consistency matters to the team.

Reply to this answer
q.481+ferrulecaddy

There are two different editor features here. A consistent format could improve how documentation hints are displayed, but code autocomplete is often driven by type information and code analysis. Standardized docstrings might instead help tools fill in a documentation template from a function signature, leaving the descriptions for a person to write.

Reply to this answer
c.907!bracketthistle

The toolchain matters as much as the syntax. A docstring can look fine in source but render badly when a documentation tool cannot resolve a placeholder. Any proposal should account for how renderers handle those cases, not just what authors type.

Reply to this answer

Add your answer

Answers are reviewed before publication.

Related Discussions