Improve method JSON descriptions

[jasonpaulos]

Currently, the JSON description field for an ABI method is simply the method's Python docstring, with all newlines turned into spaces:

pyteal/pyteal/ast/subroutine.py

Lines 630 to 637 in a66907e

	if self.subroutine.implementation.__doc__ is not None:
	spec["desc"] = " ".join(
	[
	i.strip()
	for i in self.subroutine.implementation.__doc__.split("\n")
	if not (i.isspace() or len(i) == 0)
	]
	)

This can be improved in a few ways:

1. Keep filtering out single newlines (which are used to wrap a single line in the Python docstring), but treat double newlines as a newline in the JSON doc string. For example, given the following Python function:

def example1():
    """This is an example docstring. This first line wraps since it's too
    long to fit in a single line of source code.
    
    This is a second line.
    """
    pass

We should produce this JSON string:

"This is an example docstring. This first line wraps since it's too long to fit in a single line of source code.\nThis is a second line."

2. Right now, there is no way to populate the description fields of arguments or return values. I propose that we adopt some way to parse a Python docstring and extract information about these fields, using the existing Python docstring conventions. For example, given the following Python function:

def example2(a: abi.Uint8, b: abi.Uint32, *, output: abi.Uint64):
    """This is a second example docstring.
    
    Args:
        a: A description for the first argument.
        b: A description for the second argument.
    
    Returns:
        A description for the return value.
    """
    pass

We should produce the following method JSON:

{
  "name": "example2",
  "args": [
    {
      "type": "uint8",
      "name": "a",
      "desc": "A description for the first argument."
    },
    {
      "type": "uint32",
      "name": "b",
      "desc": "A description for the second argument."
    }
  ],
  "returns": {
    "type": "uint64",
    "desc": "A description for the return value."
  },
  "desc": "This is a second example docstring."
}

[cusma]

Which docstring format should we use? I think the most popular in Python are:

• Epytext
• reST used by Sphinx (and default in JetBrains PyCharm)
• Goolge (also supported by Python IDEs like PyCharm)
• NumPy

I personally find the Google docstring style guide the best one in terms of readability, and I think we are already using it in pyteal.

[jasonpaulos]

Good point, I forget there is more than just the Google format sometimes 😅

I'd prefer supporting Google, but if we use a library like docstring_parser, it appears to support all 4 of those formats.