Yehowshua/ZIm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Refine syntax highlighting for Python docstrings (#20898)

Browse source 
Following up on #20763, this PR adds support for module- and class-level
docstrings, adds "additional docstrings" as described in [PEP
257](https://peps.python.org/pep-0257/), and fixes function-level
docstrings so that only the first string literal in a function gets
treated as a docstring.

One question that occurs to me is: Would it be good to capture attribute
and additional docstrings differently from regular docstrings? E.g.
`@string.doc.attribute`, `@string.doc.additional`? PEP 257 mentions that
unlike regular docstrings, these docstrings are ignored by the
interpreter (regular docstrings get added as the `__doc__` property of
the object they document), so I can see someone potentially wanting to
style them a little differently.

Release notes:

* Added Python syntax highlighting for class- and module-level
docstrings, additional docstrings, and improved recognition of
function-level docstrings.

Co-authored-by: Piotr Osiewicz <24362066+osiewicz@users.noreply.github.com>
This commit is contained in:
jfmontanaro 2025-01-28 04:23:43 -05:00 • committed by GitHub
parent b643080117
commit bb59e7f217
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 12 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

18
crates/languages/src/python/highlights.scm
View file

@ -128,33 +128,39 @@
"}" @punctuation.special) @embedded "}" @punctuation.special) @embedded
; Docstrings. ; Docstrings.
(module
.(expression_statement (string) @string.doc)+)
(class_definition
body: (block .(expression_statement (string) @string.doc)+))
(function_definition (function_definition
"async"? "async"?
"def" "def"
name: (_) name: (_)
(parameters)? (parameters)?
body: (block . (expression_statement (string) @string.doc))) body: (block .(expression_statement (string) @string.doc)+))
(class_definition (class_definition
body: (block body: (block
. (comment) @comment* . (comment) @comment*
. (expression_statement (string) @string.doc))) . (expression_statement (string) @string.doc)+))
(module (module
. (comment) @comment* . (comment) @comment*
. (expression_statement (string) @string.doc)) . (expression_statement (string) @string.doc)+)
(module (module
[ [
(expression_statement (assignment)) (expression_statement (assignment))
(type_alias_statement) (type_alias_statement)
] ]
. (expression_statement (string) @string.doc)) . (expression_statement (string) @string.doc)+)
(class_definition (class_definition
body: (block body: (block
(expression_statement (assignment)) (expression_statement (assignment))
. (expression_statement (string) @string.doc))) . (expression_statement (string) @string.doc)+))
(class_definition (class_definition
body: (block body: (block
@ -163,7 +169,7 @@
(#eq? @function.method.constructor "__init__") (#eq? @function.method.constructor "__init__")
body: (block body: (block
(expression_statement (assignment)) (expression_statement (assignment))
. (expression_statement (string) @string.doc))))) . (expression_statement (string) @string.doc)+))))
[ [