Add example documentation of docstring formats (#224)

README.md

@@ -18,14 +18,14 @@ Visual Studio Code extension to quickly generate docstrings for python functions
 
 ## Docstring Formats
 
-To turn of type generation in docstrings use the `-notypes` template of the desired format. The docBlockr format is a typed version of PEP0257.
-
--   Google (default)
--   docBlockr
--   Numpy
--   Sphinx
--   one-line-sphinx
--   PEP0257
+To turn off type generation in docstrings use the `-notypes` template of the desired format. The docBlockr format is a typed version of PEP0257.
+
+-   [google](docs/google.md)
+-   [sphinx](docs/sphinx.md)
+-   [numpy](docs/numpy.md)
+-   [docBlockr](docs/docblockr.md)
+-   [one-line-sphinx](docs/one-line-sphinx.md)
+-   [pep257](docs/pep257.md)
 
 ## Usage
 

docs/docblockr.md

@@ -0,0 +1,27 @@
+# docBlockr Docstring Format
+
+```python
+def abc(a: int, c = [1,2]):
+    """_summary_
+
+    Arguments:
+        a {int} -- _description_
+
+    Keyword Arguments:
+        c {list} -- _description_ (default: {[1,2]})
+
+    Raises:
+        AssertionError: _description_
+
+    Returns:
+        _type_ -- _description_
+    """
+    if a > 10:
+        raise AssertionError("a is more than 10")
+
+    return c
+    if a > 10:
+        raise AssertionError("a is more than 10")
+
+    return c
+```

docs/google.md

@@ -0,0 +1,21 @@
+# Google Docstring Format
+
+```python
+def abc(a: int, c = [1,2]):
+    """_summary_
+
+    Args:
+        a (int): _description_
+        c (list, optional): _description_. Defaults to [1,2].
+
+    Raises:
+        AssertionError: _description_
+
+    Returns:
+        _type_: _description_
+    """
+    if a > 10:
+        raise AssertionError("a is more than 10")
+
+    return c
+```

docs/numpy.md

@@ -0,0 +1,28 @@
+# Numpy Docstring Format
+
+```python
+def abc(a: int, c = [1,2]):
+    """_summary_
+
+    Parameters
+    ----------
+    a : int
+        _description_
+    c : list, optional
+        _description_, by default [1,2]
+
+    Returns
+    -------
+    _type_
+        _description_
+
+    Raises
+    ------
+    AssertionError
+        _description_
+    """
+    if a > 10:
+        raise AssertionError("a is more than 10")
+
+    return c
+```

docs/one-line-sphinx.md

@@ -0,0 +1,16 @@
+# One Line Sphinx Docstring Format
+
+```python
+def abc(a: int, c = [1,2]):
+    """_summary_
+
+    :param int a: _description_
+    :param list c: _description_, defaults to [1,2]
+    :raises AssertionError: _description_
+    :return _type_: _description_
+    """
+    if a > 10:
+        raise AssertionError("a is more than 10")
+
+    return c
+```

docs/pep257.md

@@ -0,0 +1,23 @@
+# Pep257 Docstring Format
+
+```python
+def abc(a: int, c = [1,2]):
+    """_summary_
+
+    Arguments:
+        a -- _description_
+
+    Keyword Arguments:
+        c -- _description_ (default: {[1,2]})
+
+    Raises:
+        AssertionError: _description_
+
+    Returns:
+        _description_
+    """
+    if a > 10:
+        raise AssertionError("a is more than 10")
+
+    return c
+```

docs/sphinx.md

@@ -0,0 +1,19 @@
+# Sphinx Docstring Format
+
+```python
+def abc(a: int, c = [1,2]):
+    """_summary_
+
+    :param a: _description_
+    :type a: int
+    :param c: _description_, defaults to [1,2]
+    :type c: list, optional
+    :raises AssertionError: _description_
+    :return: _description_
+    :rtype: _type_
+    """
+    if a > 10:
+        raise AssertionError("a is more than 10")
+
+    return c
+```