Fix statistics module ldoc descriptions

Follows PR review.

Use ldoc aliases for types and [opt] for optional parameters. Fix
typos and outdated info in descriptions. Fix incorrect description
of argument table fields. Use @Local for local functions. Wrap
language constructions in backticks.

It is not clear how to describe modules with constants for ldoc.
ldoc-styled description for `crud.stats.operation` is available
at `crud.stats.module`. See [1] for possible updates.

1. lunarmodules/ldoc#369

Follows up #224

Author: DifferentialOrange

crud/stats/local_registry.lua

@@ -1,3 +1,6 @@
+---- Module
+-- @module crud.stats.local_registry
+--
 local errors = require('errors')
 
 local dev_checks = require('crud.common.dev_checks')
@@ -9,18 +12,19 @@ local registry = {}
 local internal = stash.get('local_registry')
 local StatsLocalError = errors.new_class('StatsLocalError', {capture_stack = false})
 
---- Initialize local metrics registry
+--- Initialize local metrics registry.
 --
 --  Registries are not meant to used explicitly
 --  by users, init is not guaranteed to be idempotent.
 --
 -- @function init
--- @tparam table opts
 --
---  @tfield boolean quantiles
---   Quantiles is not supported for local, only `false` is valid.
+-- @tab opts
+--
+-- @bool opts.quantiles
+--  Quantiles is not supported for local, only `false` is valid.
 --
--- @treturn boolean Returns true.
+-- @treturn boolean Returns `true`.
 --
 function registry.init(opts)
     dev_checks({ quantiles = 'boolean' })
@@ -36,35 +40,35 @@ function registry.init(opts)
     return true
 end
 
---- Destroy local metrics registry
+--- Destroy local metrics registry.
 --
 --  Registries are not meant to used explicitly
 --  by users, destroy is not guaranteed to be idempotent.
 --
 -- @function destroy
 --
--- @treturn boolean Returns true.
+-- @treturn boolean Returns `true`.
 --
 function registry.destroy()
     internal.registry = nil
 
     return true
 end
 
---- Get copy of local metrics registry
+--- Get copy of local metrics registry.
 --
 --  Registries are not meant to used explicitly
 --  by users, get is not guaranteed to work without init.
 --
 -- @function get
 --
--- @tparam string space_name
---  (Optional) If specified, returns table with statistics
+-- @string[opt] space_name
+--  If specified, returns table with statistics
 --  of operations on table, separated by operation type and
 --  execution status. If there wasn't any requests for table,
---  returns {}. In not specified, returns table with statistics
---  about all existing spaces and count of calls to spaces
---  that wasn't found.
+--  returns `{}`. If not specified, returns table with statistics
+--  about all existing spaces, count of calls to spaces
+--  that wasn't found and count of schema reloads.
 --
 -- @treturn table Returns copy of metrics registry (or registry section).
 --
@@ -78,39 +82,39 @@ function registry.get(space_name)
     return table.deepcopy(internal.registry)
 end
 
---- Check if space statistics are present in registry
+--- Check if space statistics are present in registry.
 --
 -- @function is_unknown_space
 --
--- @tparam string space_name
+-- @string space_name
 --  Name of space.
 --
--- @treturn boolean True, if space stats found. False otherwise.
+-- @treturn boolean `true`, if space stats found. `false` otherwise.
 --
 function registry.is_unknown_space(space_name)
     dev_checks('string')
 
     return internal.registry.spaces[space_name] == nil
 end
 
---- Increase requests count and update latency info
+--- Increase requests count and update latency info.
 --
 -- @function observe
 --
--- @tparam string space_name
+-- @string space_name
 --  Name of space.
 --
--- @tparam number latency
+-- @number latency
 --  Time of call execution.
 --
--- @tparam string op
+-- @string op
 --  Label of registry collectors.
---  Use `require('crud.common.const').OP` to pick one.
+--  Use `require('crud.stats.module').op` to pick one.
 --
--- @tparam string success
---  'ok' if no errors on execution, 'error' otherwise.
+-- @string success
+--  `'ok'` if no errors on execution, `'error'` otherwise.
 --
--- @treturn boolean Returns true.
+-- @treturn boolean Returns `true`.
 --
 function registry.observe(latency, space_name, op, status)
     dev_checks('number', 'string', 'string', 'string')
@@ -125,32 +129,32 @@ function registry.observe(latency, space_name, op, status)
     return true
 end
 
---- Increase count of "space not found" collector by one
+--- Increase count of "space not found" collector by one.
 --
 -- @function observe_space_not_found
 --
--- @treturn boolean Returns true.
+-- @treturn boolean Returns `true`.
 --
 function registry.observe_space_not_found()
     internal.registry.space_not_found = internal.registry.space_not_found + 1
 
     return true
 end
 
---- Increase statistics of storage select/pairs calls
+--- Increase statistics of storage select/pairs calls.
 --
 -- @function observe_fetch
 --
--- @tparam string space_name
+-- @string space_name
 --  Name of space.
 --
--- @tparam number tuples_fetched
+-- @number tuples_fetched
 --  Count of tuples fetched during storage call.
 --
--- @tparam number tuples_lookup
+-- @number tuples_lookup
 --  Count of tuples looked up on storages while collecting response.
 --
--- @treturn boolean Returns true.
+-- @treturn boolean Returns `true`.
 --
 function registry.observe_fetch(tuples_fetched, tuples_lookup, space_name)
     dev_checks('number', 'number', 'string')
@@ -165,17 +169,17 @@ function registry.observe_fetch(tuples_fetched, tuples_lookup, space_name)
     return true
 end
 
---- Increase statistics of planned map reduces during select/pairs
+--- Increase statistics of planned map reduces during select/pairs.
 --
 -- @function observe_map_reduces
 --
--- @tparam number count
+-- @number count
 --  Count of map reduces planned.
 --
--- @tparam string space_name
+-- @string space_name
 --  Name of space.
 --
--- @treturn boolean Returns true.
+-- @treturn boolean Returns `true`.
 --
 function registry.observe_map_reduces(count, space_name)
     dev_checks('number', 'string')
@@ -189,14 +193,14 @@ function registry.observe_map_reduces(count, space_name)
     return true
 end
 
---- Increase statistics of schema reloads
+--- Increase statistics of schema reloads.
 --
 -- @function observe_schema_reloads
 --
--- @tparam number count
+-- @number count
 --  Schema reloads performed.
 --
--- @treturn boolean Returns true.
+-- @treturn boolean Returns `true`.
 --
 function registry.observe_schema_reloads(count)
     dev_checks('number')