From c248dca6eeaa6994fc3ab663f431238266417241 Mon Sep 17 00:00:00 2001
From: Kaarle Ritvanen <kaarle.ritvanen@datakunkku.fi>
Date: Fri, 16 Dec 2016 14:51:28 +0200
Subject: doc: section for field constructor parameters

---
 aconf/model/init.lua | 85 +++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 78 insertions(+), 7 deletions(-)

(limited to 'aconf/model/init.lua')

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
-- 
cgit v1.2.3