From 2cc92ad225ef0fd2756b44c9dc81c59fedbf2f20 Mon Sep 17 00:00:00 2001
From: Kaarle Ritvanen <kaarle.ritvanen@datakunkku.fi>
Date: Fri, 16 Dec 2016 13:11:53 +0200
Subject: doc: add clarifications and clean up

---
 aconf/model/field.lua | 10 +++++-----
 aconf/model/init.lua  | 16 ++++++++--------
 aconf/model/model.lua | 12 +++++-------
 aconf/model/net.lua   |  4 ++--
 4 files changed, 20 insertions(+), 22 deletions(-)

(limited to 'aconf/model')

diff --git a/aconf/model/field.lua b/aconf/model/field.lua
index daaa9f4..70930d7 100644
--- a/aconf/model/field.lua
+++ b/aconf/model/field.lua
@@ -1,5 +1,5 @@
 --[[
-Copyright (c) 2012-2015 Kaarle Ritvanen
+Copyright (c) 2012-2016 Kaarle Ritvanen
 See LICENSE file for license details
 --]]
 
@@ -450,10 +450,10 @@ function M.TreeNode:validate_saved(context)
 end
 
 
---- model field, inherits @{Field}. The value of this field is a <a
--- href="#Model_objects">model object</a> conforming to the specified
--- model. A model field with default parameters is implicitly created
--- when a model is used in lieu of a @{Field}.
+--- model field, inherits @{Field}. The value of this field is a
+-- [model object](#Model_objects) conforming to the specified model. A
+-- model field with default parameters is implicitly created when a
+-- model is used in lieu of a @{Field}.
 -- @klass Model
 -- @param model (<i>[&lt;Model&gt;](#new)</i>) model describing the
 -- structure of the model objects
diff --git a/aconf/model/init.lua b/aconf/model/init.lua
index 6c78b8f..35dfc7b 100644
--- a/aconf/model/init.lua
+++ b/aconf/model/init.lua
@@ -1,5 +1,5 @@
 --[[
-Copyright (c) 2012-2015 Kaarle Ritvanen
+Copyright (c) 2012-2016 Kaarle Ritvanen
 See LICENSE file for license details
 --]]
 
@@ -206,6 +206,13 @@ 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.
+-- @tparam ?string ui_member user-friendly noun for a member of this
+-- collection
 M.Collection = class(fld.TreeNode)
 
 function M.Collection:init(params, itype)
@@ -231,13 +238,6 @@ function M.Collection:auto_ui_name(name)
    return super(self, M.Collection):auto_ui_name(name)
 end
 
---- 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.
--- @tparam ?string ui_member user-friendly noun for a member of this
--- collection
 function M.Collection:load(context, options)
    if not self.iparams.field then
       self.iparams.field = to_field(self.type)
diff --git a/aconf/model/model.lua b/aconf/model/model.lua
index bf31f17..7417115 100644
--- a/aconf/model/model.lua
+++ b/aconf/model/model.lua
@@ -1,5 +1,5 @@
 --[[
-Copyright (c) 2012-2015 Kaarle Ritvanen
+Copyright (c) 2012-2016 Kaarle Ritvanen
 See LICENSE file for license details
 --]]
 
@@ -72,7 +72,6 @@ end
 -- key&ndash;value pairs. The key will be the name of the field and
 -- the value will determine its type. The value shall be a subclass of
 -- @{Field}, an instance of such, or another **&lt;Model&gt;**.
--- @function new
 -- @param base (optional <i>**&lt;Model&gt;**</i>) base model
 -- inherited by the new model.
 -- @return <i>**&lt;Model&gt;**</i> new model
@@ -110,6 +109,8 @@ end
 
 --- Model objects. Each of these represents an actual model
 -- object in the data model, in the context of a specific transaction.
+-- These are instances of @{node.TreeNode} and the model class created
+-- e.g. using @{new}.
 -- @section Model
 M.Model = M.new(node.TreeNode)
 
@@ -250,14 +251,11 @@ function M.Model:init(context)
 end
 
 --- fetch an object in the context of the model object's transaction.
--- @function Model:fetch
+-- @function fetch
 -- @tparam string path path of the object to fetch. A path relative to
 -- the model object's own path may be used.
 -- @return (<i>**primitive**</i> or <i>@{node.TreeNode}</i>) fetched
--- object. An instance of @{node.TreeNode} represents a non-leaf
--- object in the data model, in the context of a specific
--- transaction. Model objects themselves are a special case of such
--- objects.
+-- object
 function M.Model:fetch(path, create)
    return getmetatable(self).fetch(path, create)
 end
diff --git a/aconf/model/net.lua b/aconf/model/net.lua
index 8ca7921..cc3a1e6 100644
--- a/aconf/model/net.lua
+++ b/aconf/model/net.lua
@@ -1,5 +1,5 @@
 --[[
-Copyright (c) 2012-2015 Kaarle Ritvanen
+Copyright (c) 2012-2016 Kaarle Ritvanen
 See LICENSE file for license details
 --]]
 
@@ -169,7 +169,7 @@ function M.IPv6Address:mask2cidr(mask) return mask end
 function M.IPv6Address:cidr2mask(cidr) return cidr end
 
 
---- IP address field, inherits @{Field}. Accepts both IPv4 and IPv6
+--- IP address field, inherits @{String}. Accepts both IPv4 and IPv6
 -- address values.
 -- @klass net.IPAddress
 M.IPAddress = class(Union)
-- 
cgit v1.2.3