feat: add enums to args (#45)

Author: Duologic

doc-util/README.md

@@ -18,14 +18,14 @@ local d = import "github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet"
 
 ## Index
 
-* [`fn arg(name, type, default)`](#fn-arg)
+* [`fn arg(name, type, default, enums)`](#fn-arg)
 * [`fn fn(help, args)`](#fn-fn)
 * [`fn obj(help, fields)`](#fn-obj)
 * [`fn pkg(name, url, help, filename='', version='master')`](#fn-pkg)
 * [`fn render(obj)`](#fn-render)
 * [`fn val(type, help, default)`](#fn-val)
 * [`obj argument`](#obj-argument)
-  * [`fn new(name, type, default)`](#fn-argumentnew)
+  * [`fn new(name, type, default, enums)`](#fn-argumentnew)
 * [`obj func`](#obj-func)
   * [`fn new(help, args)`](#fn-funcnew)
   * [`fn withArgs(args)`](#fn-funcwithargs)
@@ -45,7 +45,7 @@ local d = import "github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet"
 ### fn arg
 
 ```ts
-arg(name, type, default)
+arg(name, type, default, enums)
 ```
 
 `arg` is a shorthand for `argument.new`
@@ -107,10 +107,22 @@ Utilities for creating function arguments
 #### fn argument.new
 
 ```ts
-new(name, type, default)
+new(name, type, default, enums)
+```
+
+`new` creates a new function argument, taking the `name`, the `type`. Optionally it
+can take a `default` value and `enum`-erate potential values.
+
+Examples:
+
+```jsonnet
+[
+  d.argument.new('foo', d.T.string),
+  d.argument.new('bar', d.T.string, default='loo'),
+  d.argument.new('baz', d.T.number, enums=[1,2,3]),
+]
 ```
 
-new creates a new function argument, taking the name, the type and optionally a default value
 
 ### obj func
 

doc-util/main.libsonnet

@@ -119,11 +119,30 @@
 
   '#argument': d.obj('Utilities for creating function arguments'),
   argument:: {
-    '#new': d.fn('new creates a new function argument, taking the name, the type and optionally a default value', [d.arg('name', d.T.string), d.arg('type', d.T.string), d.arg('default', d.T.any)]),
-    new(name, type, default=null): {
+    '#new': d.fn(|||
+      `new` creates a new function argument, taking the `name`, the `type`. Optionally it
+      can take a `default` value and `enum`-erate potential values.
+
+      Examples:
+
+      ```jsonnet
+      [
+        d.argument.new('foo', d.T.string),
+        d.argument.new('bar', d.T.string, default='loo'),
+        d.argument.new('baz', d.T.number, enums=[1,2,3]),
+      ]
+      ```
+    |||, [
+      d.arg('name', d.T.string),
+      d.arg('type', d.T.string),
+      d.arg('default', d.T.any),
+      d.arg('enums', d.T.array),
+    ]),
+    new(name, type, default=null, enums=null): {
       name: name,
       type: type,
       default: default,
+      enums: enums,
     },
   },
   '#arg': self.argument['#new'] + self.func.withHelp('`arg` is a shorthand for `argument.new`'),

doc-util/render.libsonnet

@@ -203,9 +203,31 @@
         for arg in self.doc.args
       ]),
 
+      enums: std.join('', [
+        if arg.enums != null
+        then '\n\nAccepted values for `%s` are ' % arg.name
+             + (
+               std.join(', ', [
+                 std.toString(item)
+                 for item in arg.enums
+               ])
+             )
+        else ''
+        for arg in self.doc.args
+      ]),
+
       linkName: '%(name)s(%(args)s)' % self,
 
-      content: '```ts\n%(name)s(%(args)s)\n```\n\n%(help)s' % self,
+      content:
+        (|||
+           ```ts
+           %(name)s(%(args)s)
+           ```
+
+         ||| % self)
+        + '%(help)s' % self
+        + '%(enums)s' % self,
+      // odd concatenation to prevent unintential newline changes
 
     },