From 3baaf91de453d35b095881478be8d88b3fc2b97a Mon Sep 17 00:00:00 2001 From: Kaarle Ritvanen Date: Thu, 2 Apr 2015 16:34:13 +0300 Subject: initial developer documentation descriptions for all functions and classes used by the openssh module --- aconf/model/config.ld | 6 ++++++ aconf/model/field.lua | 38 ++++++++++++++++++++++++++++++++++++++ aconf/model/init.lua | 8 ++++++++ aconf/model/model.lua | 8 ++++++++ aconf/model/permission.lua | 6 +++++- aconf/model/root.lua | 8 ++++++++ aconf/model/service.lua | 8 ++++++++ 7 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 aconf/model/config.ld (limited to 'aconf') diff --git a/aconf/model/config.ld b/aconf/model/config.ld new file mode 100644 index 0000000..54c9473 --- /dev/null +++ b/aconf/model/config.ld @@ -0,0 +1,6 @@ +--[[ +Copyright (c) 2012-2015 Kaarle Ritvanen +See LICENSE file for license details +--]] + +new_type('klass', 'Classes', false, 'Constructor parameters') diff --git a/aconf/model/field.lua b/aconf/model/field.lua index 6e4607f..1b44931 100644 --- a/aconf/model/field.lua +++ b/aconf/model/field.lua @@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen See LICENSE file for license details --]] +--- @module aconf.model local M = {} local err = require('aconf.error') @@ -56,6 +57,39 @@ function M.conv_filter(filter) end + +--- base class for fields. The constructor accepts a table argument +-- containing field parameters as key–value pairs. The parameters +-- listed below are valid for all subclasses. Subclasses may define +-- additional parameters. +-- @klass Field +-- @tparam ?string addr 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. +-- @tparam ?|nil|string|{[string]=string,...} be_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. +-- @tparam nil|{any|{any,string},...} choice 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. +-- @tparam ?any default default value for the field +-- @tparam ?boolean required field must be assigned a value if set, +-- defaults to false +-- @tparam ?string ui_name user-friendly name for the field. M.Field = class(M.Member) function M.Field:init(params) @@ -263,6 +297,8 @@ function Primitive:validate(context, value) end +--- string field, inherits @{Field}. +-- @klass String M.String = class(Primitive) function M.String:init(params) @@ -317,6 +353,8 @@ function M.Integer:validate(context, value) end +--- boolean field, inherits @{Field}. +-- @klass Boolean M.Boolean = class(Primitive) function M.Boolean:init(params) diff --git a/aconf/model/init.lua b/aconf/model/init.lua index 437cb93..667da2f 100644 --- a/aconf/model/init.lua +++ b/aconf/model/init.lua @@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen See LICENSE file for license details --]] +--- @module aconf.model local M = {} M.error = require('aconf.error') @@ -241,6 +242,13 @@ function M.Collection:load(context, options) end +--- list field, inherits @{Field}. A list is an ordered collection of +--- members. The path of a list member is that of the list augmented +--- by the index of the member. +-- @klass List +-- @tparam Field|Model type subclass of @{Field}, instance of such, or +-- subclass of Model specifying the type of the members. +-- @tparam ?string ui_member user-friendly noun for a list member. M.List = class(M.Collection) function M.List:init(params) super(self, M.List):init(params, node.List) end diff --git a/aconf/model/model.lua b/aconf/model/model.lua index a1780c9..3ffd4d3 100644 --- a/aconf/model/model.lua +++ b/aconf/model/model.lua @@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen See LICENSE file for license details --]] +--- @module aconf.model local M = {} local raise = require('aconf.error').raise @@ -66,6 +67,13 @@ function M.Action:meta(context) end +--- create a new model. The model's fields can be defined after its +-- creation by assigning it key–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 a subclass +-- of Model. +-- @tparam ?Model base base model inherited by the new model +-- @treturn Model new model function M.new(base) if not base then base = M.Model end diff --git a/aconf/model/permission.lua b/aconf/model/permission.lua index f7f5be1..8ddd144 100644 --- a/aconf/model/permission.lua +++ b/aconf/model/permission.lua @@ -1,8 +1,9 @@ --[[ -Copyright (c) 2012-2014 Kaarle Ritvanen +Copyright (c) 2012-2015 Kaarle Ritvanen See LICENSE file for license details --]] +--- @module aconf.model local M = {} local node = require('aconf.model.node') @@ -15,6 +16,9 @@ function M.define(path, ...) txn:commit() end +--- create default permissions (read, create, modify, delete) for a given path. +-- @function permission.defaults +-- @tparam string path path to create the permissions for function M.defaults(path) M.define(path, 'read', 'create', 'modify', 'delete') for _, action in ipairs(node.meta(start_txn():fetch(path)).actions or {}) do diff --git a/aconf/model/root.lua b/aconf/model/root.lua index 3f95b0e..eef48ec 100644 --- a/aconf/model/root.lua +++ b/aconf/model/root.lua @@ -3,6 +3,7 @@ Copyright (c) 2012-2015 Kaarle Ritvanen See LICENSE file for license details --]] +--- @module aconf.model local M = {} local model = require('aconf.model.model') @@ -60,6 +61,13 @@ M.topology = setmetatable( } ) +--- inject a new field to the root model. +-- @tparam string name name of the field +-- @tparam Field|Model field type of the field, specified by a +-- subclass of @{Field} or an instance of such. Can also be specified +-- by a subclass of Model. +-- @tparam ?{[string]=any,...} params field parameters. Applicable +-- when field type is specified by a class (not an instance). function M.register(name, field, params) if not params then params = {} end params.create = true diff --git a/aconf/model/service.lua b/aconf/model/service.lua index 2d129fa..9ce3685 100644 --- a/aconf/model/service.lua +++ b/aconf/model/service.lua @@ -3,12 +3,20 @@ Copyright (c) 2012-2015 Kaarle Ritvanen See LICENSE file for license details --]] +--- @module aconf.model + local fld = require('aconf.model.field') local new = require('aconf.model.model').new local super = require('aconf.object').super local pth = require('aconf.path') local store = require('aconf.persistence') +--- create a model corresponding to an OpenRC service. +-- @function service +-- @tparam string name name of the service +-- @treturn Model new model, which has two pre-defined boolean fields, +-- *enabled* and *status*, for controlling the service's lifecycle and +-- inspecting its current status. return function(name) local res = new() -- cgit v1.2.3