Rewrote LuaDoc.

1 files changed, 81 insertions, 72 deletions

diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua
index 6f19163e..5f42fcdc 100644
--- a/modules/textadept/adeptsense.lua
+++ b/modules/textadept/adeptsense.lua
@@ -194,7 +194,7 @@ local M = {}
 --
 -- ### Summary
 --
--- The above method of setting syntax options, ctags kinds, and trigger
+-- The above method of setting syntax options, Ctags kinds, and trigger
 -- characters for an Adeptsense is sufficient for most static and some dynamic
 -- languages. The rest of this document is devoted to more complex techniques.
 --
@@ -367,7 +367,7 @@ local M = {}
 -- @field always_show_globals (bool)
 --   Include globals in the list of completions offered.
 --   Globals are classes, functions, and fields that do not belong to another
---   class. They are contained in `completions['']`.
+--   class. They are contained in `sense.completions['']`.
 --   The default value is `true`.
 -- @field FUNCTIONS (string)
 --   XPM image for Adeptsense functions.
@@ -393,7 +393,8 @@ M.FIELD = 'fields'
 ---
 -- Returns a full symbol (if any) and current symbol part (if any) behind the
 -- caret.
--- For example: `buffer.cur` would return `'buffer'` and `'cur'`.
+-- For example: `buffer.cur` would return `'buffer'` and `'cur'`. Returns empty
+-- strings instead of `nil`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @return symbol or `''`
 -- @return part or `''`
@@ -408,11 +409,11 @@ function M.get_symbol(sense)
 end
 
 ---
--- Returns the class name for a given symbol.
--- If the symbol is `sense.syntax.self` and a class definition using the
--- `sense.syntax.class_definition` keyword is found, that class is returned.
--- Otherwise the buffer is searched backwards for a type declaration of the
--- symbol according to the patterns in `sense.syntax.type_declarations`.
+-- Returns the class name for *symbol* name.
+-- If *symbol* is `sense.syntax.self` and inside a class definition matching
+-- `sense.syntax.class_definition`, that class is returned. Otherwise the
+-- buffer is searched backwards for a type declaration of *symbol* according to
+-- the patterns in `sense.syntax.type_declarations`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get the class of.
 -- @return class or `nil`
@@ -504,13 +505,14 @@ local function add_inherited(sense, class, only_fields, only_funcs, c, added)
 end
 
 ---
--- Returns a list of completions for the given symbol.
+-- Returns a list of function (unless *only_fields* is `true`) and field (unless
+-- *only_funcs* is `true`) completions for *symbol* name.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get completions for.
--- @param only_fields If `true`, returns list of only fields. The default value
---   is `false`.
--- @param only_functions If `true`, returns list of only functions. The default
---   value is `false`.
+-- @param only_fields Optional flag indicating whether or not to return a list
+--   of only fields. The default value is `false`.
+-- @param only_functions Optional flag indicating whether or not to return a
+--   list of only functions. The default value is `false`.
 -- @return completion_list or `nil`
 -- @name get_completions
 function M.get_completions(sense, symbol, only_fields, only_functions)
@@ -560,13 +562,15 @@ function M.get_completions(sense, symbol, only_fields, only_functions)
 end
 
 ---
--- Shows an autocompletion list for the symbol behind the caret.
+-- Shows an autocompletion list of functions (unless *only_fields* is `true`)
+-- and fields (unless *only_funcs* is `true`) for the symbol behind the caret,
+-- returning `true` on success.
 -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses
 --   the current language's Adeptsense (if it exists).
--- @param only_fields If `true`, returns list of only fields. The default value
---   is `false`.
--- @param only_functions If `true`, returns list of only functions. The default
---   value is `false`.
+-- @param only_fields Optional flag indicating whether or not to return a list
+--   of only fields. The default value is `false`.
+-- @param only_functions Optional flag indicating whether or not to return a
+--   list of only functions. The default value is `false`.
 -- @return `true` on success or `false`.
 -- @see get_symbol
 -- @see get_completions
@@ -592,14 +596,16 @@ function M.complete(sense, only_fields, only_functions)
 end
 
 ---
--- Sets the trigger for autocompletion.
+-- Sets the trigger character(s) *c* for autocompletion.
+-- If *only_fields* is `true`, the trigger only completes fields. If
+-- *only_functions* is `true`, the trigger only completes functions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param c The character(s) that triggers the autocompletion. You can have up
 --   to two characters.
--- @param only_fields If `true`, this trigger only completes fields. The default
---   value is `false`.
--- @param only_functions If `true`, this trigger only completes functions.
---   The default value is `false`.
+-- @param only_fields Optional flag indicating whether or not this trigger only
+--   completes fields. The default value is `false`.
+-- @param only_functions Optional flag indicating whether or not this trigger
+--   only completes functions. The default value is `false`.
 -- @usage sense:add_trigger('.')
 -- @usage sense:add_trigger(':', false, true) -- only functions
 -- @usage sense:add_trigger('->')
@@ -617,9 +623,8 @@ function M.add_trigger(sense, c, only_fields, only_functions)
 end
 
 ---
--- Returns a list of apidocs for the given symbol.
--- If there are multiple apidocs, the index of one to display is the value of
--- the `pos` key in the returned list.
+-- Returns a list of apidocs for *symbol* name.
+-- The list contains a `pos` key with the index of the apidoc to show.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param symbol The symbol to get apidocs for.
 -- @return apidoc_list or `nil`
@@ -656,7 +661,7 @@ end
 
 local apidocs = nil
 ---
--- Shows a calltip with API documentation for the symbol behind the caret.
+-- Shows a call tip with API documentation for the symbol behind the caret.
 -- If documentation is already being shown, cycles through multiple definitions.
 -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses
 --   the current language's Adeptsense (if it exists).
@@ -705,14 +710,16 @@ events.connect(events.CALL_TIP_CLICK, function(position)
 end)
 
 ---
--- Loads the given ctags file for autocompletion.
--- It is recommended to pass `-n` to ctags in order to use line numbers instead
--- of text patterns to locate tags. This will greatly reduce memory usage for a
--- large number of symbols if `nolocations` is not `true`.
+-- Loads the Ctags file *tag_file* for autocompletions.
+-- If *nolocations* is `true`, `sense:goto_ctag()` cannot be used with this set
+-- of tags. It is recommended to pass `-n` to `ctags` in order to use line
+-- numbers instead of text patterns to locate tags. This will greatly reduce
+-- memory usage for a large number of symbols if `nolocations` is `false`.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
--- @param tag_file The path of the ctags file to load.
--- @param nolocations If `true`, does not store the locations of the tags for
---   use by `goto_ctag()`. The default value is `false`.
+-- @param tag_file The path of the Ctags file to load.
+-- @param nolocations Optional flag indicating whether or not to discard the
+--   locations of the tags for use by `sense:goto_ctag()`. The default value is
+--   `false`.
 -- @name load_ctags
 function M.load_ctags(sense, tag_file, nolocations)
   local ctags_kinds = sense.ctags_kinds
@@ -785,21 +792,21 @@ function M.load_ctags(sense, tag_file, nolocations)
 end
 
 ---
--- Displays a filtered list dialog of all known symbols of the given kind
--- (classes, functions, fields, etc.) and jumps to the source of the selected
--- one.
+-- Prompts the user to select a symbol to jump to from a list of all known
+-- symbols of kind *kind* (classes, functions, fields, etc.) shown in a filtered
+-- list dialog whose title text is *title*.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
--- @param k The ctag character kind (e.g. `'f'` for a Lua function).
+-- @param kind The Ctag character kind (e.g. `'f'` for a Lua function).
 -- @param title The title for the filtered list dialog.
 -- @name goto_ctag
-function M.goto_ctag(sense, k, title)
-  if not sense.locations[k] then return end -- no ctags loaded
+function M.goto_ctag(sense, kind, title)
+  if not sense.locations[kind] then return end -- no Ctags loaded
   local items = {}
-  local kind = sense.ctags_kinds[k]
-  for k, v in pairs(sense.locations[k]) do
-    items[#items + 1] = k:match('[^#]+$') -- symbol name
+  local kind = sense.ctags_kinds[kind]
+  for kind, v in pairs(sense.locations[kind]) do
+    items[#items + 1] = kind:match('[^#]+$') -- symbol name
     if kind == M.FUNCTION or kind == M.FIELD then
-      items[#items + 1] = k:match('^[^#]+') -- class name
+      items[#items + 1] = kind:match('^[^#]+') -- class name
     end
     items[#items + 1] = v[1]..':'..v[2]
   end
@@ -825,21 +832,21 @@ function M.goto_ctag(sense, k, title)
 end
 
 ---
--- Called by `load_ctags()` when a ctag kind is not recognized.
--- This method should be replaced with your own that is specific to the
--- language.
+-- Called by `load_ctags()` when a Ctag kind is not recognized.
+-- The parameters are extracted from Ctags' [tag format][]. This method should
+-- be replaced with your own that is specific to the language.
+--
+-- [tag format]: http://ctags.sourceforge.net/ctags.html#TAG%20FILE%20FORMAT
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @param tag_name The tag name.
 -- @param file_name The name of the file the tag belongs to.
--- @param ex_cmd The `ex_cmd` returned by ctags.
--- @param ext_fields The `ext_fields` returned by ctags.
+-- @param ex_cmd The `ex_cmd` returned by Ctags.
+-- @param ext_fields The `ext_fields` returned by Ctags.
 -- @name handle_ctag
 function M.handle_ctag(sense, tag_name, file_name, ex_cmd, ext_fields) end
 
 ---
--- Clears an Adeptsense.
--- This is necessary for loading a new ctags file or completions from a
--- different project.
+-- Clears the Adeptsense for loading new Ctags or project files.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
 -- @name clear
 function M.clear(sense)
@@ -851,7 +858,7 @@ function M.clear(sense)
 end
 
 ---
--- Called when clearing an Adeptsense.
+-- Called when clearing the Adeptsense.
 -- This function should be replaced with your own if you have any persistant
 -- objects that need to be deleted.
 -- @param sense The Adeptsense returned by `adeptsense.new()`.
@@ -859,7 +866,7 @@ end
 function M.handle_clear(sense) end
 
 ---
--- Creates a new Adeptsense for the given lexer language.
+-- Creates and returns a new Adeptsense for *lang* name.
 -- Only one sense can exist per language.
 -- @param lang The lexer language to create an Adeptsense for.
 -- @return adeptsense
@@ -883,7 +890,7 @@ function M.new(lang)
     always_show_globals = true,
 
 ---
--- Contains a map of ctags kinds to Adeptsense kinds.
+-- A map of Ctags kinds to Adeptsense kinds.
 -- Recognized kinds are `FUNCTION`, `FIELD`, and `CLASS`. Classes are quite
 -- simply containers for functions and fields so Lua modules would count as
 -- classes. Any other kinds will be passed to `handle_ctag()` for user-defined
@@ -901,13 +908,14 @@ function M.new(lang)
 ctags_kinds = {},
 
 ---
--- Contains a map of classes and a list of their inherited classes.
+-- A map of classes and a list of their inherited classes, normally populated by
+-- `load_ctags()`.
 -- @class table
 -- @name inherited_classes
 inherited_classes = {},
 
 ---
--- Contains lists of possible completions for known symbols.
+-- A list containing lists of possible completions for known symbols.
 -- Each symbol key has a table value that contains a list of field completions
 -- with a `fields` key and a list of functions completions with a `functions`
 -- key. This table is normally populated by `load_ctags()`, but can also be set
@@ -917,14 +925,14 @@ inherited_classes = {},
 completions = {},
 
 ---
--- Contains the locations of known symbols.
--- This table is populated by `load_ctags()`.
+-- A list of the locations of known symbols, normally populated by
+-- `load_ctags()`.
 -- @class table
 -- @name locations
 locations = {},
 
 ---
--- Contains a list of api files used by `show_apidoc()`.
+-- A list of api files used by `show_apidoc()`.
 -- Each line in the api file contains a symbol name (not the full symbol)
 -- followed by a space character and then the symbol's documentation. Since
 -- there may be many duplicate symbol names, it is recommended to put the full
@@ -937,35 +945,36 @@ locations = {},
 api_files = {},
 
 ---
--- Contains syntax-specific values for the language.
--- @field self The language's syntax-equivalent of `self`. Default is `'self'`.
+-- Map of language-specific syntax settings.
+-- @field self The language's syntax-equivalent of `self`. The default value is
+--   `'self'`.
 -- @field class_definition A Lua pattern representing the language's class
 --   definition syntax. The first capture returned must be the class name. A
 --   second, optional capture contains the class' superclass (if any). If no
 --   completions are found for the class name, completions for the superclass
 --   are shown (if any). Completions will not be shown for both a class and
---   superclass unless defined in a previously loaded ctags file. Also, multiple
---   superclasses cannot be recognized by this pattern; use a ctags file
+--   superclass unless defined in a previously loaded Ctags file. Also, multiple
+--   superclasses cannot be recognized by this pattern; use a Ctags file
 --   instead. The default value is `'class%s+([%w_]+)'`.
 -- @field word_chars A Lua pattern of characters allowed in a word.
---   The default is `'%w_'`.
+--   The default value is `'%w_'`.
 -- @field symbol_chars A Lua pattern of characters allowed in a symbol,
 --   including member operators. The pattern should be a character set.
---   The default is `'[%w_%.]'`.
+--   The default value is `'[%w_%.]'`.
 -- @field type_declarations A list of Lua patterns used for determining the
 --   class type of a symbol. The first capture returned must be the class name.
 --   Use `%_` to match the symbol.
 --   The default value is `'(%u[%w_%.]+)%s+%_'`.
 -- @field type_declarations_exclude A table of types to exclude, even if they
---   match a type_declaration pattern. Each excluded type is a table key and has
---   a `true` boolean value. For example, `{Foo = true}` excludes any type whose
---   name is `Foo`.
+--   match a `type_declarations` pattern. Each excluded type is a table key and
+--   has a `true` boolean value. For example, `{Foo = true}` excludes any type
+--   whose name is `Foo`.
 --   The default value is `{}`.
 -- @field type_assignments A map of Lua patterns to class types for variable
---   assignments. This is typically used for dynamically typed languages. For
---   example, `sense.type_assignments['^"'] = 'string'`  would recognize string
+--   assignments, typically used for dynamically typed languages. For example,
+--   `sense.syntax.type_assignments['^"'] = 'string'`  would recognize string
 --   assignments in Lua so the `foo` in `foo = "bar"` would be recognized as
---   type `string`. The class type value can contain pattern captures.
+--   type `string`. The class type value may contain `%n` pattern captures.
 -- @class table
 -- @name syntax
 -- @see get_class