Repository navigation
Read Epydoc's synonyms of field names - #163
Merged
Merged
Conversation
Epydoc's manual gives synonyms for its fields: @raises, @except and @exception for @raise, @returns for @return, @returntype for @rtype, @parameter, @arg and @argument for @PARAM, and @kwarg and @kwparam for @Keyword. They were read as plain text metas, so a raises written as @raises had no type and a @returntype typed nothing. Read them as the fields they stand for, keeping the name written as the key. Compose still writes the canonical names.
rr-
force-pushed
the
rework/35-epydoc-fields
branch
from
November 6, 2026 17:25
e72cc57 to
d63693c
Compare
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
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.
Epydoc's manual gives several fields synonyms, and Twisted and other projects use them. Until now the parser only knew the canonical names, so the synonyms came out as plain text metas:
Before,
d.raisesandd.returnswere empty. There were three text metas, and the@returntypetyped nothing. Now there is a raises of typeValueErrorand a returnR.of typeint.The synonyms, as the Epydoc manual lists them:
@param@parameter,@arg,@argument@keyword@kwarg,@kwparam@return@returns@rtype@returntype@raise@raises,@except,@exceptionEach meta keeps the name it was written with as its
key.compose()still writes the canonical names, so@raisescomes out as@raise, and that reads back as the same raises. The synonyms are also indefault_sections("epydoc"), so users building their own field list start from them.Parity: 6 of 29,127 docstrings differ, all case inputs. Two are real Twisted docstrings (
twisted.conch.ssh._kex.getKexandtwisted.protocols.ftp.FTP.ftp_NLST.listErr), which now give a raises and a return instead of text metas. The other four are the new cases. No stdlib or generated docstrings changed.Bench on 3.8: parse is 0.98–1.00x of main.