feat(lib): fn.withArgs

doc-util/README.md

@@ -0,0 +1,137 @@
+---
+permalink: /
+---
+
+# package d
+
+```jsonnet
+local d = import "github.com/sh0rez/docsonnet/doc-util"
+```
+
+`doc-util` provides a Jsonnet interface for `docsonnet`,
+ a Jsonnet API doc generator that uses structured data instead of comments.
+
+
+## Index
+
+* [`fn arg(name, type, default)`](#fn-arg)
+* [`fn fn(help, args)`](#fn-fn)
+* [`fn obj(help, fields)`](#fn-obj)
+* [`fn pkg(name, url, help)`](#fn-pkg)
+* [`obj argument`](#obj-argument)
+  * [`fn new(name, type, default)`](#fn-argumentnew)
+* [`obj func`](#obj-func)
+  * [`fn new(help, args)`](#fn-funcnew)
+  * [`fn withArgs(args)`](#fn-funcwithargs)
+  * [`fn withHelp(help)`](#fn-funcwithhelp)
+* [`obj object`](#obj-object)
+  * [`fn new(help, fields)`](#fn-objectnew)
+  * [`fn withFields(fields)`](#fn-objectwithfields)
+* [`obj package`](#obj-package)
+  * [`fn new(name, url, help)`](#fn-packagenew)
+
+## Fields
+
+### fn arg
+
+```ts
+arg(name, type, default)
+```
+
+`arg` is a shorthand for `argument.new`
+
+### fn fn
+
+```ts
+fn(help, args)
+```
+
+`fn` is a shorthand for `func.new`
+
+### fn obj
+
+```ts
+obj(help, fields)
+```
+
+`obj` is a shorthand for `object.new`
+
+### fn pkg
+
+```ts
+pkg(name, url, help)
+```
+
+`new` is a shorthand for `package.new`
+
+## obj argument
+
+Utilities for creating function arguments
+
+### fn argument.new
+
+```ts
+new(name, type, default)
+```
+
+new creates a new function argument, taking the name, the type and optionally a default value
+
+## obj func
+
+Utilities for documenting Jsonnet methods (functions of objects)
+
+### fn func.new
+
+```ts
+new(help, args)
+```
+
+new creates a new function, optionally with description and arguments
+
+### fn func.withArgs
+
+```ts
+withArgs(args)
+```
+
+The `withArgs` modifier overrides the arguments of that function
+
+### fn func.withHelp
+
+```ts
+withHelp(help)
+```
+
+The `withHelp` modifier overrides the help text of that function
+
+## obj object
+
+Utilities for documenting Jsonnet objects (`{ }`).
+
+### fn object.new
+
+```ts
+new(help, fields)
+```
+
+new creates a new object, optionally with description and fields
+
+### fn object.withFields
+
+```ts
+withFields(fields)
+```
+
+The `withFields` modifier overrides the fields property of an already created object
+
+## obj package
+
+
+
+### fn package.new
+
+```ts
+new(name, url, help)
+```
+
+new creates a new package with given `name`, `import` URL and `help` text

doc-util/main.libsonnet

@@ -51,6 +51,11 @@
     withHelp(help):: { 'function'+: {
       help: help,
     } },
+
+    '#withArgs': d.fn('The `withArgs` modifier overrides the arguments of that function', [d.arg('args', d.T.array)]),
+    withArgs(args):: { 'function'+: {
+      args: args,
+    } },
   },
 
   '#fn': self.func['#new'] + d.func.withHelp('`fn` is a shorthand for `func.new`'),
@@ -83,6 +88,9 @@
     array: 'array',
     any: 'any',
 
+    'null': "null",
+    nil: self["null"],
+
     func: 'function',
     'function': self.func,
   },

pkg/docsonnet/fast.go

@@ -98,9 +98,13 @@ func loadField(name string, field map[string]interface{}, parent map[string]inte
 }
 
 func loadFn(name string, msi map[string]interface{}) Field {
+	h, ok := msi["help"].(string)
+	if !ok {
+		h = ""
+	}
 	fn := Function{
 		Name: name,
-		Help: msi["help"].(string),
+		Help: h,
 	}
 	if args, ok := msi["args"]; ok {
 		fn.Args = loadArgs(args.([]interface{}))

pkg/render/render_test.go

@@ -0,0 +1,48 @@
+package render
+
+import (
+	"testing"
+
+	"github.com/sh0rez/docsonnet/pkg/docsonnet"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSortFields(t *testing.T) {
+	api := docsonnet.Fields{
+		"new":      dfn(),
+		"newNamed": dfn(),
+
+		"aaa": dfn(),
+		"bbb": dobj(),
+		"ccc": dfn(),
+
+		"metadata": dobj(),
+	}
+
+	sorted := []string{
+		"new",
+		"newNamed",
+
+		"aaa",
+		"ccc",
+
+		"bbb",
+		"metadata",
+	}
+
+	res := sortFields(api)
+
+	assert.Equal(t, sorted, res)
+}
+
+func dobj() docsonnet.Field {
+	return docsonnet.Field{
+		Object: &docsonnet.Object{},
+	}
+}
+
+func dfn() docsonnet.Field {
+	return docsonnet.Field{
+		Function: &docsonnet.Function{},
+	}
+}