cli, docs: Add a docs command for doc generation

This took a lot longer than it looks to get right. It's not perfect, but
it now reliably generates documentation which we can put into gohugo.

lang/core/example/answer.go

@@ -42,8 +42,12 @@ const Answer = 42
 func init() {
 	simple.ModuleRegister(ModuleName, "answer", &simple.Scaffold{
 		T: types.NewType("func() int"),
-		F: func(context.Context, []types.Value) (types.Value, error) {
-			return &types.IntValue{V: Answer}, nil
-		},
+		F: TheAnswerToLifeTheUniverseAndEverything,
 	})
 }
+
+// TheAnswerToLifeTheUniverseAndEverything returns the Answer to Life, the
+// Universe and Everything.
+func TheAnswerToLifeTheUniverseAndEverything(context.Context, []types.Value) (types.Value, error) {
+	return &types.IntValue{V: Answer}, nil
+}

lang/core/example/errorbool.go

@@ -40,13 +40,17 @@ import (
 func init() {
 	simple.ModuleRegister(ModuleName, "errorbool", &simple.Scaffold{
 		T: types.NewType("func(a bool) str"),
-		F: func(ctx context.Context, input []types.Value) (types.Value, error) {
-			if input[0].Bool() {
-				return nil, fmt.Errorf("we errored on request")
-			}
-			return &types.StrValue{
-				V: "set input to true to generate an error",
-			}, nil
-		},
+		F: ErrorBool,
 	})
 }
+
+// ErrorBool causes this function to error if you pass it true. Otherwise it
+// returns a string reminding you how to use it.
+func ErrorBool(ctx context.Context, input []types.Value) (types.Value, error) {
+	if input[0].Bool() {
+		return nil, fmt.Errorf("we errored on request")
+	}
+	return &types.StrValue{
+		V: "set input to true to generate an error",
+	}, nil
+}

lang/core/example/int2str.go

@@ -40,10 +40,13 @@ import (
 func init() {
 	simple.ModuleRegister(ModuleName, "int2str", &simple.Scaffold{
 		T: types.NewType("func(a int) str"),
-		F: func(ctx context.Context, input []types.Value) (types.Value, error) {
-			return &types.StrValue{
-				V: fmt.Sprintf("%d", input[0].Int()),
-			}, nil
-		},
+		F: Int2Str,
 	})
 }
+
+// Int2Str takes an int, and returns it as a string.
+func Int2Str(ctx context.Context, input []types.Value) (types.Value, error) {
+	return &types.StrValue{
+		V: fmt.Sprintf("%d", input[0].Int()),
+	}, nil
+}

lang/core/example/str2int.go

@@ -40,14 +40,18 @@ import (
 func init() {
 	simple.ModuleRegister(ModuleName, "str2int", &simple.Scaffold{
 		T: types.NewType("func(a str) int"),
-		F: func(ctx context.Context, input []types.Value) (types.Value, error) {
-			var i int64
-			if val, err := strconv.ParseInt(input[0].Str(), 10, 64); err == nil {
-				i = val
-			}
-			return &types.IntValue{
-				V: i,
-			}, nil
-		},
+		F: Str2Int,
 	})
 }
+
+// Str2Int takes an str, and returns it as an int. If it can't convert it, it
+// returns 0.
+func Str2Int(ctx context.Context, input []types.Value) (types.Value, error) {
+	var i int64
+	if val, err := strconv.ParseInt(input[0].Str(), 10, 64); err == nil {
+		i = val
+	}
+	return &types.IntValue{
+		V: i,
+	}, nil
+}