Move inline documentation into separate files.

Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>

4 files changed, 415 insertions, 202 deletions

diff --git a/modules/luci-base/luasrc/model/ipkg.lua b/modules/luci-base/luasrc/model/ipkg.lua
index 216caa5cca..587637272d 100644
--- a/modules/luci-base/luasrc/model/ipkg.lua
+++ b/modules/luci-base/luasrc/model/ipkg.lua
@@ -15,7 +15,6 @@ local table = table
 local ipkg = "opkg --force-removal-of-dependent-packages --force-overwrite --nocase"
 local icfg = "/etc/opkg.conf"
 
---- LuCI OPKG call abstraction library
 module "luci.model.ipkg"
 
 
@@ -93,54 +92,31 @@ local function _lookup(act, pkg)
 end
 
 
---- Return information about installed and available packages.
--- @param pkg Limit output to a (set of) packages
--- @return Table containing package information
 function info(pkg)
 	return _lookup("info", pkg)
 end
 
---- Return the package status of one or more packages.
--- @param pkg Limit output to a (set of) packages
--- @return Table containing package status information
 function status(pkg)
 	return _lookup("status", pkg)
 end
 
---- Install one or more packages.
--- @param ... List of packages to install
--- @return Boolean indicating the status of the action
--- @return OPKG return code, STDOUT and STDERR
 function install(...)
 	return _action("install", ...)
 end
 
---- Determine whether a given package is installed.
--- @param pkg Package
--- @return Boolean
 function installed(pkg)
 	local p = status(pkg)[pkg]
 	return (p and p.Status and p.Status.installed)
 end
 
---- Remove one or more packages.
--- @param ... List of packages to install
--- @return Boolean indicating the status of the action
--- @return OPKG return code, STDOUT and STDERR
 function remove(...)
 	return _action("remove", ...)
 end
 
---- Update package lists.
--- @return Boolean indicating the status of the action
--- @return OPKG return code, STDOUT and STDERR
 function update()
 	return _action("update")
 end
 
---- Upgrades all installed packages.
--- @return Boolean indicating the status of the action
--- @return OPKG return code, STDOUT and STDERR
 function upgrade()
 	return _action("upgrade")
 end
@@ -174,33 +150,19 @@ function _list(action, pat, cb)
 	end
 end
 
---- List all packages known to opkg.
--- @param pat	Only find packages matching this pattern, nil lists all packages
--- @param cb	Callback function invoked for each package, receives name, version and description as arguments
--- @return	nothing
 function list_all(pat, cb)
 	_list("list", pat, cb)
 end
 
---- List installed packages.
--- @param pat	Only find packages matching this pattern, nil lists all packages
--- @param cb	Callback function invoked for each package, receives name, version and description as arguments
--- @return	nothing
 function list_installed(pat, cb)
 	_list("list_installed", pat, cb)
 end
 
---- Find packages that match the given pattern.
--- @param pat	Find packages whose names or descriptions match this pattern, nil results in zero results
--- @param cb	Callback function invoked for each patckage, receives name, version and description as arguments
--- @return	nothing
 function find(pat, cb)
 	_list("find", pat, cb)
 end
 
 
---- Determines the overlay root used by opkg.
--- @return		String containing the directory path of the overlay root.
 function overlay_root()
 	local od = "/"
 	local fd = io.open(icfg, "r")
diff --git a/modules/luci-base/luasrc/model/ipkg.luadoc b/modules/luci-base/luasrc/model/ipkg.luadoc
new file mode 100644
index 0000000000..cf0985f94a
--- /dev/null
+++ b/modules/luci-base/luasrc/model/ipkg.luadoc
@@ -0,0 +1,109 @@
+---[[
+LuCI OPKG call abstraction library
+
+module "luci.model.ipkg"
+]]
+
+---[[
+Return information about installed and available packages.
+
+@class function
+@name info
+@param pkg Limit output to a (set of) packages
+@return Table containing package information
+]]
+
+---[[
+Return the package status of one or more packages.
+
+@class function
+@name status
+@param pkg Limit output to a (set of) packages
+@return Table containing package status information
+]]
+
+---[[
+Install one or more packages.
+
+@class function
+@name install
+@param ... List of packages to install
+@return Boolean indicating the status of the action
+@return OPKG return code, STDOUT and STDERR
+]]
+
+---[[
+Determine whether a given package is installed.
+
+@class function
+@name installed
+@param pkg Package
+@return Boolean
+]]
+
+---[[
+Remove one or more packages.
+
+@class function
+@name remove
+@param ... List of packages to install
+@return Boolean indicating the status of the action
+@return OPKG return code, STDOUT and STDERR
+]]
+
+---[[
+Update package lists.
+
+@class function
+@name update
+@return Boolean indicating the status of the action
+@return OPKG return code, STDOUT and STDERR
+]]
+
+---[[
+Upgrades all installed packages.
+
+@class function
+@name upgrade
+@return Boolean indicating the status of the action
+@return OPKG return code, STDOUT and STDERR
+]]
+
+---[[
+List all packages known to opkg.
+
+@class function
+@name list_all
+@param pat	Only find packages matching this pattern, nil lists all packages
+@param cb	Callback function invoked for each package, receives name, version and description as arguments
+@return	nothing
+]]
+
+---[[
+List installed packages.
+
+@class function
+@name list_installed
+@param pat	Only find packages matching this pattern, nil lists all packages
+@param cb	Callback function invoked for each package, receives name, version and description as arguments
+@return	nothing
+]]
+
+---[[
+Find packages that match the given pattern.
+
+@class function
+@name find
+@param pat	Find packages whose names or descriptions match this pattern, nil results in zero results
+@param cb	Callback function invoked for each patckage, receives name, version and description as arguments
+@return	nothing
+]]
+
+---[[
+Determines the overlay root used by opkg.
+
+@class function
+@name overlay_root
+@return		String containing the directory path of the overlay root.
+]]
+
diff --git a/modules/luci-base/luasrc/model/uci.lua b/modules/luci-base/luasrc/model/uci.lua
index 8ac82773f3..1659137742 100644
--- a/modules/luci-base/luasrc/model/uci.lua
+++ b/modules/luci-base/luasrc/model/uci.lua
@@ -12,26 +12,18 @@ local require, getmetatable = require, getmetatable
 local error, pairs, ipairs = error, pairs, ipairs
 local type, tostring, tonumber, unpack = type, tostring, tonumber, unpack
 
---- LuCI UCI model library.
 -- The typical workflow for UCI is:  Get a cursor instance from the
 -- cursor factory, modify data (via Cursor.add, Cursor.delete, etc.),
 -- save the changes to the staging area via Cursor.save and finally
 -- Cursor.commit the data to the actual config files.
 -- LuCI then needs to Cursor.apply the changes so deamons etc. are
 -- reloaded.
--- @cstyle	instance
 module "luci.model.uci"
 
---- Create a new UCI-Cursor.
--- @class function
--- @name cursor
--- @return	UCI-Cursor
 cursor = uci.cursor
 
 APIVERSION = uci.APIVERSION
 
---- Create a new Cursor initialized to the state directory.
--- @return UCI cursor
 function cursor_state()
 	return cursor(nil, "/var/state")
 end
@@ -42,9 +34,6 @@ inst_state = cursor_state()
 
 local Cursor = getmetatable(inst)
 
---- Applies UCI configuration changes
--- @param configlist		List of UCI configurations
--- @param command			Don't apply only return the command
 function Cursor.apply(self, configlist, command)
 	configlist = self:_affected(configlist)
 	if command then
@@ -56,10 +45,6 @@ function Cursor.apply(self, configlist, command)
 end
 
 
---- Delete all sections of a given type that match certain criteria.
--- @param config		UCI config
--- @param type			UCI section type
--- @param comparator	Function that will be called for each section and
 -- returns a boolean whether to delete the current section (optional)
 function Cursor.delete_all(self, config, stype, comparator)
 	local del = {}
@@ -90,12 +75,6 @@ function Cursor.delete_all(self, config, stype, comparator)
 	end
 end
 
---- Create a new section and initialize it with data.
--- @param config	UCI config
--- @param type		UCI section type
--- @param name		UCI section name (optional)
--- @param values	Table of key - value pairs to initialize the section with
--- @return			Name of created section
 function Cursor.section(self, config, type, name, values)
 	local stat = true
 	if name then
@@ -112,10 +91,6 @@ function Cursor.section(self, config, type, name, values)
 	return stat and name
 end
 
---- Updated the data of a section using data from a table.
--- @param config	UCI config
--- @param section	UCI section name (optional)
--- @param values	Table of key - value pairs to update the section with
 function Cursor.tset(self, config, section, values)
 	local stat = true
 	for k, v in pairs(values) do
@@ -126,21 +101,11 @@ function Cursor.tset(self, config, section, values)
 	return stat
 end
 
---- Get a boolean option and return it's value as true or false.
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option
--- @return			Boolean
 function Cursor.get_bool(self, ...)
 	local val = self:get(...)
 	return ( val == "1" or val == "true" or val == "yes" or val == "on" )
 end
 
---- Get an option or list and return values as table.
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option
--- @return			UCI value
 function Cursor.get_list(self, config, section, option)
 	if config and section and option then
 		local val = self:get(config, section, option)
@@ -149,12 +114,6 @@ function Cursor.get_list(self, config, section, option)
 	return nil
 end
 
---- Get the given option from the first section with the given type.
--- @param config	UCI config
--- @param type		UCI section type
--- @param option	UCI option (optional)
--- @param default	Default value (optional)
--- @return			UCI value
 function Cursor.get_first(self, conf, stype, opt, def)
 	local rv = def
 
@@ -178,12 +137,6 @@ function Cursor.get_first(self, conf, stype, opt, def)
 	return rv
 end
 
---- Set given values as list.
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option
--- @param value		UCI value
--- @return			Boolean whether operation succeeded
 function Cursor.set_list(self, config, section, option, value)
 	if config and section and option then
 		return self:set(
@@ -238,10 +191,8 @@ function Cursor._affected(self, configlist)
 	return reloadlist
 end
 
---- Create a sub-state of this cursor. The sub-state is tied to the parent
 -- curser, means it the parent unloads or loads configs, the sub state will
 -- do so as well.
--- @return			UCI state cursor tied to the parent cursor
 function Cursor.substate(self)
 	Cursor._substates = Cursor._substates or { }
 	Cursor._substates[self] = Cursor._substates[self] or cursor_state()
@@ -265,118 +216,18 @@ function Cursor.unload(self, ...)
 end
 
 
---- Add an anonymous section.
--- @class function
--- @name Cursor.add
--- @param config	UCI config
--- @param type		UCI section type
--- @return			Name of created section
-
---- Get a table of saved but uncommitted changes.
--- @class function
--- @name Cursor.changes
--- @param config	UCI config
--- @return			Table of changes
--- @see Cursor.save
-
---- Commit saved changes.
--- @class function
--- @name Cursor.commit
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.revert
--- @see Cursor.save
-
---- Deletes a section or an option.
--- @class function
--- @name Cursor.delete
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option (optional)
--- @return			Boolean whether operation succeeded
-
---- Call a function for every section of a certain type.
--- @class function
--- @name Cursor.foreach
--- @param config	UCI config
--- @param type		UCI section type
--- @param callback	Function to be called
--- @return			Boolean whether operation succeeded
-
---- Get a section type or an option
--- @class function
--- @name Cursor.get
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option (optional)
--- @return			UCI value
-
---- Get all sections of a config or all values of a section.
--- @class function
--- @name Cursor.get_all
--- @param config	UCI config
--- @param section	UCI section name (optional)
--- @return			Table of UCI sections or table of UCI values
-
---- Manually load a config.
--- @class function
--- @name Cursor.load
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.save
--- @see Cursor.unload
-
---- Revert saved but uncommitted changes.
--- @class function
--- @name Cursor.revert
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.commit
--- @see Cursor.save
-
---- Saves changes made to a config to make them committable.
--- @class function
--- @name Cursor.save
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.load
--- @see Cursor.unload
-
---- Set a value or create a named section.
--- @class function
--- @name Cursor.set
--- @param config	UCI config
--- @param section	UCI section name
--- @param option	UCI option or UCI section type
--- @param value		UCI value or nil if you want to create a section
--- @return			Boolean whether operation succeeded
-
---- Get the configuration directory.
--- @class function
--- @name Cursor.get_confdir
--- @return			Configuration directory
-
---- Get the directory for uncomitted changes.
--- @class function
--- @name Cursor.get_savedir
--- @return			Save directory
-
---- Set the configuration directory.
--- @class function
--- @name Cursor.set_confdir
--- @param directory	UCI configuration directory
--- @return			Boolean whether operation succeeded
-
---- Set the directory for uncommited changes.
--- @class function
--- @name Cursor.set_savedir
--- @param directory	UCI changes directory
--- @return			Boolean whether operation succeeded
-
---- Discard changes made to a config.
--- @class function
--- @name Cursor.unload
--- @param config	UCI config
--- @return			Boolean whether operation succeeded
--- @see Cursor.load
--- @see Cursor.save
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/modules/luci-base/luasrc/model/uci.luadoc b/modules/luci-base/luasrc/model/uci.luadoc
new file mode 100644
index 0000000000..1c208669d1
--- /dev/null
+++ b/modules/luci-base/luasrc/model/uci.luadoc
@@ -0,0 +1,291 @@
+---[[
+LuCI UCI model library.
+
+The typical workflow for UCI is:  Get a cursor instance from the
+cursor factory, modify data (via Cursor.add, Cursor.delete, etc.),
+save the changes to the staging area via Cursor.save and finally
+Cursor.commit the data to the actual config files.
+LuCI then needs to Cursor.apply the changes so deamons etc. are
+reloaded.
+@cstyle	instance
+module "luci.model.uci"
+]]
+
+---[[
+Create a new UCI-Cursor.
+
+@class function
+@name cursor
+@return	UCI-Cursor
+]]
+
+---[[
+Create a new Cursor initialized to the state directory.
+
+@class function
+@name cursor_state
+@return UCI cursor
+]]
+
+---[[
+Applies UCI configuration changes
+
+@class function
+@name Cursor.apply
+@param configlist		List of UCI configurations
+@param command			Don't apply only return the command
+]]
+
+---[[
+Delete all sections of a given type that match certain criteria.
+
+@class function
+@name Cursor.delete_all
+@param config		UCI config
+@param type			UCI section type
+@param comparator	Function that will be called for each section and
+returns a boolean whether to delete the current section (optional)
+]]
+
+---[[
+Create a new section and initialize it with data.
+
+@class function
+@name Cursor.section
+@param config	UCI config
+@param type		UCI section type
+@param name		UCI section name (optional)
+@param values	Table of key - value pairs to initialize the section with
+@return			Name of created section
+]]
+
+---[[
+Updated the data of a section using data from a table.
+
+@class function
+@name Cursor.tset
+@param config	UCI config
+@param section	UCI section name (optional)
+@param values	Table of key - value pairs to update the section with
+]]
+
+---[[
+Get a boolean option and return it's value as true or false.
+
+@class function
+@name Cursor.get_bool
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option
+@return			Boolean
+]]
+
+---[[
+Get an option or list and return values as table.
+
+@class function
+@name Cursor.get_list
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option
+@return			UCI value
+]]
+
+---[[
+Get the given option from the first section with the given type.
+
+@class function
+@name Cursor.get_first
+@param config	UCI config
+@param type		UCI section type
+@param option	UCI option (optional)
+@param default	Default value (optional)
+@return			UCI value
+]]
+
+---[[
+Set given values as list.
+
+@class function
+@name Cursor.set_list
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option
+@param value		UCI value
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Create a sub-state of this cursor. The sub-state is tied to the parent
+
+curser, means it the parent unloads or loads configs, the sub state will
+do so as well.
+@class function
+@name Cursor.substate
+@return			UCI state cursor tied to the parent cursor
+]]
+
+---[[
+Add an anonymous section.
+
+@class function
+@name Cursor.add
+@param config	UCI config
+@param type		UCI section type
+@return			Name of created section
+]]
+
+---[[
+Get a table of saved but uncommitted changes.
+
+@class function
+@name Cursor.changes
+@param config	UCI config
+@return			Table of changes
+@see Cursor.save
+]]
+
+---[[
+Commit saved changes.
+
+@class function
+@name Cursor.commit
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.revert
+@see Cursor.save
+]]
+
+---[[
+Deletes a section or an option.
+
+@class function
+@name Cursor.delete
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option (optional)
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Call a function for every section of a certain type.
+
+@class function
+@name Cursor.foreach
+@param config	UCI config
+@param type		UCI section type
+@param callback	Function to be called
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Get a section type or an option
+
+@class function
+@name Cursor.get
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option (optional)
+@return			UCI value
+]]
+
+---[[
+Get all sections of a config or all values of a section.
+
+@class function
+@name Cursor.get_all
+@param config	UCI config
+@param section	UCI section name (optional)
+@return			Table of UCI sections or table of UCI values
+]]
+
+---[[
+Manually load a config.
+
+@class function
+@name Cursor.load
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.save
+@see Cursor.unload
+]]
+
+---[[
+Revert saved but uncommitted changes.
+
+@class function
+@name Cursor.revert
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.commit
+@see Cursor.save
+]]
+
+---[[
+Saves changes made to a config to make them committable.
+
+@class function
+@name Cursor.save
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.load
+@see Cursor.unload
+]]
+
+---[[
+Set a value or create a named section.
+
+@class function
+@name Cursor.set
+@param config	UCI config
+@param section	UCI section name
+@param option	UCI option or UCI section type
+@param value		UCI value or nil if you want to create a section
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Get the configuration directory.
+
+@class function
+@name Cursor.get_confdir
+@return			Configuration directory
+]]
+
+---[[
+Get the directory for uncomitted changes.
+
+@class function
+@name Cursor.get_savedir
+@return			Save directory
+]]
+
+---[[
+Set the configuration directory.
+
+@class function
+@name Cursor.set_confdir
+@param directory	UCI configuration directory
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Set the directory for uncommited changes.
+
+@class function
+@name Cursor.set_savedir
+@param directory	UCI changes directory
+@return			Boolean whether operation succeeded
+]]
+
+---[[
+Discard changes made to a config.
+
+@class function
+@name Cursor.unload
+@param config	UCI config
+@return			Boolean whether operation succeeded
+@see Cursor.load
+@see Cursor.save
+]]
+