fixes #478

Author: jph00

fastcore/docments.py

@@ -155,12 +155,15 @@ def _docments(s, returns=True, eval_str=False):
 @delegates(_docments)
 def docments(elt, full=False, **kwargs):
     "Generates a `docment`"
+    r = {}
+    params = set(signature(elt).parameters)
+    params.add('return')
+
     def _update_docments(f, r):
         if hasattr(f, '__delwrap__'): _update_docments(f.__delwrap__, r)
         r.update({k:v for k,v in _docments(f, **kwargs).items()
-                  if full or v.get('docment',None)})
+                  if k in params and (full or v.get('docment',None))})
 
-    r = {}
     _update_docments(elt, r)
     if not full: r = {k:v['docment'] for k,v in r.items()}
     return AttrDict(r)

nbs/06_docments.ipynb

@@ -435,12 +435,15 @@
     "@delegates(_docments)\n",
     "def docments(elt, full=False, **kwargs):\n",
     "    \"Generates a `docment`\"\n",
+    "    r = {}\n",
+    "    params = set(signature(elt).parameters)\n",
+    "    params.add('return')\n",
+    "\n",
     "    def _update_docments(f, r):\n",
     "        if hasattr(f, '__delwrap__'): _update_docments(f.__delwrap__, r)\n",
     "        r.update({k:v for k,v in _docments(f, **kwargs).items()\n",
-    "                  if full or v.get('docment',None)})\n",
+    "                  if k in params and (full or v.get('docment',None))})\n",
     "\n",
-    "    r = {}\n",
     "    _update_docments(elt, r)\n",
     "    if not full: r = {k:v['docment'] for k,v in r.items()}\n",
     "    return AttrDict(r)"
@@ -462,15 +465,17 @@
      "data": {
       "text/markdown": [
        "```json\n",
-       "{ 'a': 'the 1st number to add',\n",
-       "  'b': 'the 2nd number to add',\n",
-       "  'return': 'the result of adding `a` to `b`'}\n",
+       "{ 'a': 'The first operand',\n",
+       "  'b': 'This is the second of the operands to the *addition* operator.\\n'\n",
+       "       'Note that passing a negative value here is the equivalent of the '\n",
+       "       '*subtraction* operator.',\n",
+       "  'return': \"The result is calculated using Python's builtin `+` operator.\"}\n",
        "```"
       ],
       "text/plain": [
-       "{'a': 'the 1st number to add',\n",
-       " 'b': 'the 2nd number to add',\n",
-       " 'return': 'the result of adding `a` to `b`'}"
+       "{'a': 'The first operand',\n",
+       " 'b': 'This is the second of the operands to the *addition* operator.\\nNote that passing a negative value here is the equivalent of the *subtraction* operator.',\n",
+       " 'return': \"The result is calculated using Python's builtin `+` operator.\"}"
       ]
      },
      "execution_count": null,
@@ -500,21 +505,27 @@
        "```json\n",
        "{ 'a': { 'anno': 'int',\n",
        "         'default': <class 'inspect._empty'>,\n",
-       "         'docment': 'the 1st number to add'},\n",
-       "  'b': { 'anno': <class 'int'>,\n",
-       "         'default': 0,\n",
-       "         'docment': 'the 2nd number to add'},\n",
+       "         'docment': 'The first operand'},\n",
+       "  'b': { 'anno': 'int',\n",
+       "         'default': <class 'inspect._empty'>,\n",
+       "         'docment': 'This is the second of the operands to the *addition* '\n",
+       "                    'operator.\\n'\n",
+       "                    'Note that passing a negative value here is the equivalent '\n",
+       "                    'of the *subtraction* operator.'},\n",
        "  'return': { 'anno': 'int',\n",
        "              'default': <class 'inspect._empty'>,\n",
-       "              'docment': 'the result of adding `a` to `b`'}}\n",
+       "              'docment': \"The result is calculated using Python's builtin `+` \"\n",
+       "                         'operator.'}}\n",
        "```"
       ],
       "text/plain": [
-       "{'a': {'docment': 'the 1st number to add',\n",
+       "{'a': {'docment': 'The first operand',\n",
+       "  'anno': 'int',\n",
+       "  'default': inspect._empty},\n",
+       " 'b': {'docment': 'This is the second of the operands to the *addition* operator.\\nNote that passing a negative value here is the equivalent of the *subtraction* operator.',\n",
        "  'anno': 'int',\n",
        "  'default': inspect._empty},\n",
-       " 'b': {'docment': 'the 2nd number to add', 'anno': int, 'default': 0},\n",
-       " 'return': {'docment': 'the result of adding `a` to `b`',\n",
+       " 'return': {'docment': \"The result is calculated using Python's builtin `+` operator.\",\n",
        "  'anno': 'int',\n",
        "  'default': inspect._empty}}"
       ]
@@ -546,11 +557,11 @@
        "```json\n",
        "{ 'anno': <class 'int'>,\n",
        "  'default': <class 'inspect._empty'>,\n",
-       "  'docment': 'the 1st number to add'}\n",
+       "  'docment': 'The first operand'}\n",
        "```"
       ],
       "text/plain": [
-       "{'docment': 'the 1st number to add', 'anno': int, 'default': inspect._empty}"
+       "{'docment': 'The first operand', 'anno': int, 'default': inspect._empty}"
       ]
      },
      "execution_count": null,