const (
	// JSONSuffix is the output extension for the generated documentation.
	JSONSuffix = ".json"
)

type API interface {
	// Main runs everything for this setup item.
	Main(context.Context) error
}

type Config struct {
}

type FunctionInfo struct {
	// Name is the golang name of this function. This may be an actual
	// function if used by the simple API, or the name of a struct.
	Name string `json:"name"`

	// Package is the import name to use to get to this function.
	Package string `json:"package"`

	// Func is the name of the function in that package.
	Func string `json:"func"`

	// File is the file name where this function exists.
	File string `json:"file"`

	// Desc explains what this function does.
	Desc string `json:"description"`

	// Signature is the type signature of this function. If empty then the
	// signature is not known statically and it may be polymorphic.
	Signature *string `json:"signature,omitempty"`
}

type Generate struct {
	*cliUtil.DocsGenerateArgs // embedded config
	Config                    // embedded Config

	// Program is the name of this program, usually set at compile time.
	Program string

	// Version is the version of this program, usually set at compile time.
	Version string

	// Debug represents if we're running in debug mode or not.
	Debug bool

	// Logf is a logger which should be used.
	Logf func(format string, v ...interface{})
}

type Output struct {
	// Version is the sha1 or ref name of this specific version. This is
	// used if we want to generate documentation with links matching the
	// correct version. If unspecified then this assumes git master.
	Version string `json:"version"`

	// Resources contains the collection of every available resource!
	// FIXME: should this be a list instead?
	Resources map[string]*ResourceInfo `json:"resources"`

	// Functions contains the collection of every available function!
	// FIXME: should this be a list instead?
	Functions map[string]*FunctionInfo `json:"functions"`
}

type ResourceFieldInfo struct {
	// Name is what this field is called in golang format.
	Name string `json:"name"`

	// Type is the mcl type for this field.
	Type string `json:"type"`

	// Desc explains what this field does.
	Desc string `json:"description"`
}

type ResourceInfo struct {
	// Name is the golang name of this resource.
	Name string `json:"name"`

	// Kind is the kind of this resource.
	Kind string `json:"kind"`

	// File is the file name where this resource exists.
	File string `json:"file"`

	// Desc explains what this resource does.
	Desc string `json:"description"`

	// Fields is a collection of each resource field and corresponding info.
	Fields map[string]*ResourceFieldInfo `json:"fields"`
}