feat: python documentation-like output

[ghostsquad]

I think it would be helpful to allow each parameter, and return value to be explained. Additionally, whether or not an error or assertion could be raised (outside of the usual suspects)

Reference

https://pillow.readthedocs.io/en/stable/reference/Image.html#functions

---

fn pkg.something

something(o, x)

something does some stuff

PARAMETERS

• o (object) - an object
• x (any) - an array or string for blah

RETURNS

object - a fizzbuzz

ASSERTIONS

• If o or x are null

---

### fn pkg.something

```ts
something(o, x)
```

`something` does some stuff

> `PARAMETERS`

* `o (object)` - an object
* `x (any)` - an array or string for blah

> `RETURNS`

`object` - a fizzbuzz

> `ASSERTIONS`

* If `o` or `x` are null

[tombrk]

Loving this!!

For parameters, we would need to extend d.arg():

- d.argument.new(name, type, default=null)
+ d.argument.new(name, type, default=null, help="")

For both assertions and return value, d.function.new could have new parameters asserts=[] and returns=null.

In Jsonnet, this could look like this:

{
  "#greet": d.fn("`greet` says hello",
    args=[d.arg("name", d.T.string, "Name of the (person) to greet")],
    asserts=["name is a string"],
    returns=d.val(d.T.string, "A friendly message"),
  greet(name): "Hello %s!" % name,
}

d.val above does not exist, but could be introduced as a way to also document regular exposed values (#10)

[ghostsquad]

Is this a "good first issue" you think? or something you would want to tackle? I filed a bunch of issues the other night just to start the conversations. I'm more than willing to submit some PRs too. Let me know.

[tombrk]

Sure, give it a go!!