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
; Docstrings.
(module
.(expression_statement (string) @string.doc)+)
(class_definition
body: (block .(expression_statement (string) @string.doc)+))
(function_definition
"async"?
"def"
name: (_)
(parameters)?
body: (block . (expression_statement (string) @string.doc)))
body: (block .(expression_statement (string) @string.doc)+))
(class_definition
body: (block
. (comment) @comment*
. (expression_statement (string) @string.doc)))
. (expression_statement (string) @string.doc)+))
(module
. (comment) @comment*
. (expression_statement (string) @string.doc))
. (expression_statement (string) @string.doc)+)
(module
[
(expression_statement (assignment))
(type_alias_statement)
]
. (expression_statement (string) @string.doc))
. (expression_statement (string) @string.doc)+)
(class_definition
body: (block
(expression_statement (assignment))
. (expression_statement (string) @string.doc)))
. (expression_statement (string) @string.doc)+))
(class_definition
body: (block
@ -163,7 +169,7 @@
(#eq? @function.method.constructor "__init__")
body: (block
(expression_statement (assignment))
. (expression_statement (string) @string.doc)))))
. (expression_statement (string) @string.doc)+))))
[