From a9f560b4901282143d1f495d8a3a3d880f653bdd Mon Sep 17 00:00:00 2001 From: Colin Kennedy Date: Wed, 7 Jun 2023 10:33:17 -0700 Subject: [PATCH] feat(py): Added Python "Yields:" support for Google-style docstrings (#147) * Added basic Python yield support Removed syntax error Added missing docstring Added missing end statement * Bumped the minor version to 2.15.0 --- doc/neogen.txt | 4 ++- lua/neogen/configurations/python.lua | 36 ++++++++++++++++++++++ lua/neogen/generator.lua | 2 ++ lua/neogen/init.lua | 4 ++- lua/neogen/templates/google_docstrings.lua | 3 ++ lua/neogen/types/template.lua | 2 ++ 6 files changed, 49 insertions(+), 2 deletions(-) diff --git a/doc/neogen.txt b/doc/neogen.txt index c65c6b3..6fa6ed8 100644 --- a/doc/neogen.txt +++ b/doc/neogen.txt @@ -183,12 +183,14 @@ Feel free to submit a PR, I will be happy to help you ! We use semantic versioning ! (https://semver.org) Here is the current Neogen version: > - neogen.version = "2.14.1" + neogen.version = "2.15.0" < # Changelog~ Note: We will only document `major` and `minor` versions, not `patch` ones. (only X and Y in X.Y.z) +## 2.15.0~ + - Google docstrings now include "Yields:", whenever possible ## 2.14.0~ - Google docstrings now include "Raises:", whenever possible ## 2.13.0~ diff --git a/lua/neogen/configurations/python.lua b/lua/neogen/configurations/python.lua index c931a48..0aff852 100644 --- a/lua/neogen/configurations/python.lua +++ b/lua/neogen/configurations/python.lua @@ -37,6 +37,23 @@ local validate_bare_returns = function(nodes) end end + +--- Remove `i.Return` details from `nodes` if a Python generator was found. +--- +--- If there is at least one `yield` found, Python converts the function to a generator. +--- +--- In which case, any `return` statement no longer actually functions as an +--- actual "Returns:" docstring block so we need to strip them. +--- +---@param nodes table +local validate_yield_nodes = function(nodes) + if nodes[i.Yield] ~= nil and nodes[i.Return] ~= nil + then + nodes[i.Return] = nil + end +end + + return { -- Search for these nodes parent = parent, @@ -101,6 +118,20 @@ return { extract = true, as = i.Return, }, + { + retrieve = "all", + node_type = "expression_statement", + recursive = true, + subtree = { + { + retrieve = "first", + node_type = "yield", + recursive = true, + extract = true, + as = i.Yield, + }, + }, + }, { retrieve = "all", node_type = "raise_statement", @@ -149,6 +180,8 @@ return { validate_bare_returns(nodes) end + validate_yield_nodes(nodes) + local res = extractors:extract_from_matched(nodes) res[i.Tparam] = temp[i.Tparam] @@ -194,6 +227,9 @@ return { [i.Parameter] = true, [i.Return] = true, [i.ReturnTypeHint] = true, + [i.HasYield] = function(t) + return t[i.Yield] and { true } + end, [i.ArbitraryArgs] = true, [i.Kwargs] = true, [i.Throw] = true, diff --git a/lua/neogen/generator.lua b/lua/neogen/generator.lua index 6810b27..76adf7b 100644 --- a/lua/neogen/generator.lua +++ b/lua/neogen/generator.lua @@ -26,6 +26,7 @@ local function todo_text(type) [i.Tparam] = todo["tparam"], [i.Parameter] = todo["parameter"], [i.Return] = todo["return"], + [i.Yield] = todo["yield"], [i.ReturnTypeHint] = todo["return"], [i.ReturnAnonym] = todo["return"], [i.ClassName] = todo["class"], @@ -36,6 +37,7 @@ local function todo_text(type) [i.HasParameter] = todo["parameter"], [i.HasReturn] = todo["return"], [i.HasThrow] = todo["throw"], + [i.HasYield] = todo["yield"], [i.ArbitraryArgs] = todo["args"], [i.Kwargs] = todo["kwargs"], })[type] or todo["description"] diff --git a/lua/neogen/init.lua b/lua/neogen/init.lua index 2da847f..9106cb9 100644 --- a/lua/neogen/init.lua +++ b/lua/neogen/init.lua @@ -241,6 +241,8 @@ end --- --- Note: We will only document `major` and `minor` versions, not `patch` ones. (only X and Y in X.Y.z) --- +--- ## 2.15.0~ +--- - Google docstrings now include "Yields:", whenever possible --- ## 2.14.0~ --- - Google docstrings now include "Raises:", whenever possible --- ## 2.13.0~ @@ -297,7 +299,7 @@ end --- with multiple annotation conventions. ---@tag neogen-changelog ---@toc_entry Changes in neogen plugin -neogen.version = "2.14.1" +neogen.version = "2.15.0" --minidoc_afterlines_end return neogen diff --git a/lua/neogen/templates/google_docstrings.lua b/lua/neogen/templates/google_docstrings.lua index 1c29ead..8eb25ea 100644 --- a/lua/neogen/templates/google_docstrings.lua +++ b/lua/neogen/templates/google_docstrings.lua @@ -24,5 +24,8 @@ return { { i.HasReturn, "", { type = { "func" } } }, { i.HasReturn, "Returns:", { type = { "func" } } }, { i.HasReturn, " $1", { type = { "func" } } }, + { i.HasYield, "", { type = { "func" } } }, + { i.HasYield, "Yields:", { type = { "func" } } }, + { i.HasYield, " $1", { type = { "func" } } }, { nil, '"""' }, } diff --git a/lua/neogen/types/template.lua b/lua/neogen/types/template.lua index 1632ca9..2a0a190 100644 --- a/lua/neogen/types/template.lua +++ b/lua/neogen/types/template.lua @@ -13,12 +13,14 @@ template.item = { ReturnAnonym = "return_anonym", ClassName = "class_name", Throw = "throw_statement", + Yield = "expression_statement", Vararg = "varargs", Type = "type", ClassAttribute = "attributes", HasParameter = "has_parameters", HasReturn = "has_return", HasThrow = "has_throw", + HasYield = "has_yield", ArbitraryArgs = "arbitrary_args", Kwargs = "kwargs", }