From bb59e7f217c0bdf74ecd3bba9df6b99c94381d8a Mon Sep 17 00:00:00 2001 From: jfmontanaro Date: Tue, 28 Jan 2025 04:23:43 -0500 Subject: [PATCH] Refine syntax highlighting for Python docstrings (#20898) 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> --- crates/languages/src/python/highlights.scm | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/crates/languages/src/python/highlights.scm b/crates/languages/src/python/highlights.scm index 6b296574786d1b5ca8a01a9b04530cf06dd28c83..0495f87716bd2176cfc50a79a667a6049f51ef33 100644 --- a/crates/languages/src/python/highlights.scm +++ b/crates/languages/src/python/highlights.scm @@ -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)+)))) [