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?
Would a standard docstring format be worth adopting across languages?
Answers
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.
Reply to this answer
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
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
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
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.
v.481+gasketquill:
Optional is what I had in mind. Existing projects should be able to keep their current style.