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

@@ -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~

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,

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"]

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

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, '"""' },
 }

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",
 }