path: root/aconf/model/init.lua
diff options
authorKaarle Ritvanen <>2016-12-16 14:51:28 +0200
committerKaarle Ritvanen <>2016-12-18 23:02:07 +0200
commitc248dca6eeaa6994fc3ab663f431238266417241 (patch)
tree60fc868dcf8f3bcfc21a8d82265bc45420b2adaf /aconf/model/init.lua
parent2cc92ad225ef0fd2756b44c9dc81c59fedbf2f20 (diff)
doc: section for field constructor parameters
Diffstat (limited to 'aconf/model/init.lua')
1 files changed, 78 insertions, 7 deletions
diff --git a/aconf/model/init.lua b/aconf/model/init.lua
index 35dfc7b..aaf6ad0 100644
--- a/aconf/model/init.lua
+++ b/aconf/model/init.lua
@@ -206,11 +206,11 @@ end
M.Model = fld.Model
---- collection field, inherits @{Field}.
--- @klass Collection
--- @param type (<i>@{Field}</i> or <i>[&lt;Model&gt;](#new)</i>)
--- subclass of @{Field}, instance of such, or
--- [**&lt;Model&gt;**](#new) specifying the type of the members.
+--- collection field.
+-- @fcons Collection
+-- @param type (<i>[&lt;Field&gt;](#Field_constructors)</i> or
+-- <i>[&lt;Model&gt;](#new)</i>) field constructor, field instance, or
+-- model specifying the type of the members.
-- @tparam ?string ui_member user-friendly noun for a member of this
-- collection
M.Collection = class(fld.TreeNode)
@@ -251,14 +251,14 @@ end
--- list field, inherits @{Collection}. The value of this field is an
-- instance of @{node.List}.
--- @klass List
+-- @fcons List
M.List = class(M.Collection)
function M.List:init(params) super(self, M.List):init(params, node.List) end
--- set field, inherits @{Collection}. The value of this field is an
-- instance of @{node.Set}.
--- @klass Set
+-- @fcons Set
M.Set = class(M.Collection)
function M.Set:init(params)
if not params.widget and isinstance(params.type, M.Reference) then
@@ -295,4 +295,75 @@ function M.trigger(phase, addr, func) store:trigger(phase, addr, func) end
function M.defer(addr) def_store:defer(addr) end
+--- Field constructor parameters. All field constructors accept one
+-- table argument containing field parameters as key&ndash;value
+-- pairs. The parameters listed below are valid for all
+-- subclasses. Subclasses may define additional parameters.
+-- @section Field
+--- back-end address for the field. This can be an
+-- absolute address or relative to the parent's address. The top-level
+-- component of a back-end address specifies the back-end. The
+-- interpretation of the remaining components is specific to the
+-- back-end. If not specified, the address is formed by appending the
+-- field's name to the address of the parent.
+-- @tfield ?string addr
+--- back-end mode. Controls how the Augeas back-end will map addresses
+-- to Augeas paths. By default, each component of a back-end address
+-- is directly mapped to an Augeas path component. This parameter is
+-- an exception table applicable to the subtree defined by the field's
+-- address. Each key is a relative address pattern, and the
+-- corresponding value is a directive applied to matching address
+-- components. The *enumerate* directive indicates there can be
+-- several Augeas nodes matching the path and the next component is to
+-- be interpreted as an index for such nodes. The *parent-value*
+-- directive is applicable only to primitive fields and instructs the
+-- back-end not to append the last address component at all, causing
+-- the parent node's value to be accessed. If the *be\_mode* parameter
+-- is defined as a string, it is assumed to be a directive applicable
+-- to the field's own address.
+-- @field be_mode (optional <i>**string**</i> or
+-- <i>**{[string]=string,...}**</i>)
+--- array of allowed values. Each value may be a primitive value or a
+-- tuple specifying the value used by the data model and a
+-- user-friendly value.
+-- @field choice (optional <i>**{primitive**</i> or
+-- <i>**{primitive,string},...}**</i>)
+--- function for computing the value of the field when not provided by
+-- the back-end. The function gets a reference to the field's parent
+-- as an argument. If defined as a string, a method with the given
+-- name is invoked.
+-- @field compute (optional <i><b>function(@{node.TreeNode})</b></i>
+-- or <i>**string**</i>)
+--- default value for the field.
+-- @tfield ?primitive default
+--- required field must be assigned a value if set. Defaults to false.
+-- @tfield ?boolean required
+--- function for storing the value of the field. If this parameter is
+-- defined, the value of the field is not stored according to the
+-- field's back-end address. Rather, the provided function is invoked
+-- with a reference to the parent and the field value. If defined as a
+-- string, a method with the given name is invoked.
+-- @field store (optional <i><b>function(@{node.TreeNode},
+-- primitive)</b></i> or <i>**string**</i>)
+--- user-friendly name for the field.
+-- @tfield ?string ui_name
+--- visibility of the field in the user interface. Defaults to true.
+-- @tfield ?boolean visible
+--- widget for rendering the field in the user interface. The default
+-- widget for non-leaf objects is *link*, which is a hyperlink to a
+-- detailed view to the object. The *inline* widget renders a non-leaf
+-- object embedded in the parent's view.
+-- @tfield ?string widget
return M