Feature Request: Godoc-esque functionality

[michaeltlombardi]

As an application developer who wants to enable (relatively) complex modules, I want to be able to export documentation from tengo scripts/modules so that I don't have to separately hand-write documentation in another file.

Desired Functionality

If possible, I would like to have godoc-like functionality for turning tengo script comments into markdown files.

From this script:

// mymodule.tengo
rand := import("rand")
time := import("times")
seed := time.time_unix_nano(time.now())
rand.seed(seed)

// Rolls a die of specified size. If size cannot be converted to an integer, returns undefined.
//
// To roll a six-sided die and return a number between 1 and 6 (inclusive):
//     d(6)
// To roll a twenty-sided die and return a number betwenn 1 and 20 (inclusive):
//     d(20)
d := func(size) {
  size = int(size)
  if size == undefined {
    return undefined
  }
  return rand.intn(6) + 1
}

// Rolls count dice of specified size, returning an array of results.
// If count or size cannot be converted to an integer, returns an error.
//
// To roll four six sided dice: 
//     roll(4, 6)
// To roll a two twenty-sided die:
//     roll(2, 20)
roll := func(count, size) {
  rolls := []

  count = int(count)
  if count == undefined {
    return error("count must be an integer or convertible to an integer")
  }

  size = int(size)
  if size == undefined {
    return error("count must be an integer or convertible to an integer")
  }

  for n:= 0 ; n < count ; n++ {
    rolls = rolls + [d(size)]
  }

  return rolls
}

// Helper functions for rolling dice.
export {
  d: d,
  roll: roll,
}

with the command:

tengo -doc dice.md dice.tengo

create the markdown:

# dice

Helper functions for rolling dice.

## Functions

### d(size)

Rolls a die of specified size. If size cannot be converted to an integer, returns undefined.

To roll a six-sided die and return a number between 1 and 6 (inclusive):

```golang
d(6)
```

To roll a twenty-sided die and return a number betwenn 1 and 20 (inclusive):

```golang
d(20)
```

### roll(count, size)

Rolls count dice of specified size, returning an array of results.
If count or size cannot be converted to an integer, returns an error.

To roll four six sided dice: 

```golang
roll(4, 6)
```

To roll a two twenty-sided die:

```golang
roll(2, 20)
```

Then it would be fairly trivial to have my own modules automatically generate documentation as needed for putting up on a website and to provide module authors with workflows they could adopt to smooth out their own DevX.