Eliminated redundant LuaDoc.

7 files changed, 66 insertions, 168 deletions

diff --git a/core/._m.lua b/core/._m.lua
index e2ca375b..36f2f25c 100644
--- a/core/._m.lua
+++ b/core/._m.lua
@@ -37,6 +37,4 @@ module('_m')
 
 ---
 -- This module contains no functions.
-function no_functions()
-
-end
+function no_functions() end
diff --git a/core/.find.lua b/core/.find.lua
index 3f415928..0b2b3512 100644
--- a/core/.find.lua
+++ b/core/.find.lua
@@ -107,3 +107,9 @@ function find.call_replace() end
 ---
 -- Mimicks a press of the 'Replace All' button in the Find box.
 function find.call_replace_all() end
+
+---
+-- Goes to the next or previous file found relative to the file
+-- on the current line.
+-- @param next Flag indicating whether or not to go to the next file.
+function find.goto_file_in_list(next) end
diff --git a/core/.pm.lua b/core/.pm.lua
index bd82bac3..3b1ffbd8 100644
--- a/core/.pm.lua
+++ b/core/.pm.lua
@@ -7,6 +7,50 @@
 -- [Dummy file]
 module('textadept.pm')
 
+-- Usage:
+-- Interactive search:
+--   Typing text into the project manager view begins the interactive search.
+--   If the text matches ANY part of an item in the view (case sensitively), the
+--   item is highlighted and subsequent matches can be navigated to using the
+--   up/down arrow keys.
+--
+-- Customizing look and feel:
+--   There are no function calls to make that customize the look and feel of the
+--   project manager. Instead you can manipulate it via GTK rc files. The pm
+--   entry and view have widget names of 'textadept-pm-entry' and
+--   'textadept-pm-view' respectively. Resource file documentation can be found
+--   at http://library.gnome.org/devel/gtk/unstable/gtk-Resource-Files.html.
+--   My rc file is something like this:
+--
+--     pixmap_path "/usr/share/icons/Tango/:/home/mitchell/.icons/prog/"
+--
+--     style "textadept-pm-display-style" {
+--        fg[NORMAL]     = "#AAAAAA" # treeview arrows foreground
+--        fg[PRELIGHT]   = "#AAAAAA" # treeview arrows hover foreground
+--        bg[NORMAL]     = "#333333" # entry border background
+--        base[NORMAL]   = "#333333" # entry, treeview background
+--        base[ACTIVE]   = "#444444" # treeview unfocused selection background
+--        base[SELECTED] = "#444444" # entry, treeview selection background
+--        text[NORMAL]   = "#AAAAAA" # entry, treeview text foreground
+--        text[ACTIVE]   = "#AAAAAA" # treeview unfocused selection text
+--        text[SELECTED] = "#DDDDDD" # entry, treeview selection text foreground
+--
+--        stock["gtk-directory"]  = {{ "16x16/places/stock_folder.png", LTR }}
+--        stock["gtk-folder-new"] = {{ "16x16/actions/folder_new.png", LTR }}
+--        stock["prog-class"]     = {{ "class.png", LTR }}
+--        stock["prog-enum"]      = {{ "enum.png", LTR }}
+--        stock["prog-field"]     = {{ "field.png", LTR }}
+--        stock["prog-interface"] = {{ "interface.png", LTR }}
+--        stock["prog-literal"]   = {{ "literal.png", LTR }}
+--        stock["prog-method"]    = {{ "method.png", LTR }}
+--        stock["prog-namespace"] = {{ "namespace.png", LTR }}
+--        stock["prog-reference"] = {{ "reference.png", LTR }}
+--        stock["prog-struct"]    = {{ "struct.png", LTR }}
+--      }
+--
+--      widget "*textadept-pm-entry" style "textadept-pm-display-style"
+--      widget "*textadept-pm-view" style "textadept-pm-display-style"
+
 ---
 -- Textadept's project manager table.
 -- @class table
diff --git a/core/ext/command_entry.lua b/core/ext/command_entry.lua
index 890c99e9..d2a64243 100644
--- a/core/ext/command_entry.lua
+++ b/core/ext/command_entry.lua
@@ -4,11 +4,7 @@ local textadept = _G.textadept
 local locale = _G.locale
 local ce = textadept.command_entry
 
----
--- Gets completions for the current command_entry text.
--- This function is called internally and shouldn't be called by script.
--- @param command The command to complete.
--- @return sorted table of completions
+-- LuaDoc is in core/.command_entry.lua
 function ce.get_completions_for(command)
   local substring = command:match('[%w_.:]+$') or ''
   local path, o, prefix = substring:match('^([%w_.:]-)([.:]?)([%w_]*)$')
diff --git a/core/ext/find.lua b/core/ext/find.lua
index f7eb2047..b4f4efee 100644
--- a/core/ext/find.lua
+++ b/core/ext/find.lua
@@ -10,30 +10,13 @@ local MARK_FIND = 0
 local MARK_FIND_COLOR = 0x4D9999
 local previous_view
 
----
--- [Local table] Text escape sequences with their associated characters.
--- @class table
--- @name escapes
+-- LuaDoc is in core/.find.lua.
 local escapes = {
   ['\\a'] = '\a', ['\\b'] = '\b', ['\\f'] = '\f', ['\\n'] = '\n',
   ['\\r'] = '\r', ['\\t'] = '\t', ['\\v'] = '\v', ['\\\\'] = '\\'
 }
 
----
--- Finds and selects text in the current buffer.
--- This is used by the find dialog. It is recommended to use the
--- buffer:search_in_target() or buffer:search_next() and buffer:search_prev()
--- functions for scripting.
--- @param text The text to find.
--- @param next Flag indicating whether or not the search direction is forward.
--- @param flags Search flags. This is a number mask of 4 flags: match case (2),
---   whole word (4), Lua pattern (8), and in files (16) joined with binary OR.
---   If nil, this is determined based on the checkboxes in the find box.
--- @param nowrap Flag indicating whether or not the search won't wrap.
--- @param wrapped Utility flag indicating whether or not the search has wrapped
---   for displaying useful statusbar information. This flag is used and set
---   internally, and should not be set otherwise.
--- @return position of the found text or -1
+-- LuaDoc is in core/.find.lua.
 function find.find(text, next, flags, nowrap, wrapped)
   if #text == 0 then return end
   local buffer = buffer
@@ -159,17 +142,7 @@ function find.find(text, next, flags, nowrap, wrapped)
   return result
 end
 
----
--- Replaces found text.
--- This function is used by the find dialog. It is not recommended to call it
--- via scripts.
--- textadept.find.find is called first, to select any found text. The selected
--- text is then replaced by the specified replacement text.
--- This function ignores 'Find in Files'.
--- @param rtext The text to replace found text with. It can contain both Lua
---   capture items (%n where 1 <= n <= 9) for Lua pattern searches and %()
---   sequences for embedding Lua code for any search.
--- @see find.find
+-- LuaDoc is in core/.find.lua.
 function find.replace(rtext)
   if #buffer:get_sel_text() == 0 then return end
   if find.in_files then find.in_files = false end
@@ -207,16 +180,7 @@ function find.replace(rtext)
   end
 end
 
----
--- Replaces all found text.
--- This function is used by the find dialog. It is not recommended to call it
--- via scripts.
--- If any text is selected, all found text in that selection is replaced.
--- This function ignores 'Find in Files'.
--- @param ftext The text to find.
--- @param rtext The text to replace found text with.
--- @param flags The number mask identical to the one in 'find'.
--- @see find.find
+-- LuaDoc is in core/.find.lua.
 function find.replace_all(ftext, rtext, flags)
   if #ftext == 0 then return end
   if find.in_files then find.in_files = false end
@@ -296,10 +260,7 @@ local function goto_file(pos, line_num)
 end
 textadept.events.add_handler('double_click', goto_file)
 
----
--- Goes to the next or previous file found relative to the file
--- on the current line.
--- @param next Flag indicating whether or not to go to the next file.
+-- LuaDoc is in core/.find.lua.
 function find.goto_file_in_list(next)
   local orig_view = view
   for _, buffer in ipairs(textadept.buffers) do
diff --git a/core/ext/pm.lua b/core/ext/pm.lua
index 2f63e719..67cbbbfb 100644
--- a/core/ext/pm.lua
+++ b/core/ext/pm.lua
@@ -1,49 +1,5 @@
 -- Copyright 2007-2009 Mitchell mitchell<att>caladbolg.net. See LICENSE.
 
--- Usage:
--- Interactive search:
---   Typing text into the project manager view begins the interactive search.
---   If the text matches ANY part of an item in the view (case sensitively), the
---   item is highlighted and subsequent matches can be navigated to using the
---   up/down arrow keys.
---
--- Customizing look and feel:
---   There are no function calls to make that customize the look and feel of the
---   project manager. Instead you can manipulate it via GTK rc files. The pm
---   entry and view have widget names of 'textadept-pm-entry' and
---   'textadept-pm-view' respectively. Resource file documentation can be found
---   at http://library.gnome.org/devel/gtk/unstable/gtk-Resource-Files.html.
---   My rc file is something like this:
---
---     pixmap_path "/usr/share/icons/Tango/:/home/mitchell/.icons/prog/"
---
---     style "textadept-pm-display-style" {
---        fg[NORMAL]     = "#AAAAAA" # treeview arrows foreground
---        fg[PRELIGHT]   = "#AAAAAA" # treeview arrows hover foreground
---        bg[NORMAL]     = "#333333" # entry border background
---        base[NORMAL]   = "#333333" # entry, treeview background
---        base[ACTIVE]   = "#444444" # treeview unfocused selection background
---        base[SELECTED] = "#444444" # entry, treeview selection background
---        text[NORMAL]   = "#AAAAAA" # entry, treeview text foreground
---        text[ACTIVE]   = "#AAAAAA" # treeview unfocused selection text
---        text[SELECTED] = "#DDDDDD" # entry, treeview selection text foreground
---
---        stock["gtk-directory"]  = {{ "16x16/places/stock_folder.png", LTR }}
---        stock["gtk-folder-new"] = {{ "16x16/actions/folder_new.png", LTR }}
---        stock["prog-class"]     = {{ "class.png", LTR }}
---        stock["prog-enum"]      = {{ "enum.png", LTR }}
---        stock["prog-field"]     = {{ "field.png", LTR }}
---        stock["prog-interface"] = {{ "interface.png", LTR }}
---        stock["prog-literal"]   = {{ "literal.png", LTR }}
---        stock["prog-method"]    = {{ "method.png", LTR }}
---        stock["prog-namespace"] = {{ "namespace.png", LTR }}
---        stock["prog-reference"] = {{ "reference.png", LTR }}
---        stock["prog-struct"]    = {{ "struct.png", LTR }}
---      }
---
---      widget "*textadept-pm-entry" style "textadept-pm-display-style"
---      widget "*textadept-pm-view" style "textadept-pm-display-style"
-
 local pm = textadept.pm
 
 local current_browser = nil
@@ -52,24 +8,7 @@ local current_browser = nil
 local last_browser_text = nil
 local browser_cursors = {}
 
----
--- Requests treeview contents from browser that matches pm_entry's text.
--- This function is called internally and shouldn't be called by a script.
--- @param full_path A numerically indexed table of treeview item parents. The
---   first index contains the text of pm_entry. Subsequent indexes contain the
---   ID's of parents of the child requested for expanding (if any).
--- @param expanding Optional flag indicating if the contents of a parent are
---   being requested. Defaults to false.
--- @return table of tables to for display in the treeview (single level).
---   Each key in the return table is the treeview item's ID. The table value
---   has the following recognized fields:
---     parent - boolean value indicating if this entry can contain children. If
---       true, an expanding arrow is displayed next to the entry.
---     pixbuf - a string representing a GTK stock-id whose icon is displayed
---       next to an entry.
---     text - the entry's Pango marked-up display text.
---   Note that only a SINGLE level of data needs to be returned. When parents
---   are expanded, this function is called again to get that level of data.
+-- LuaDoc is in core/.browser.lua.
 function pm.get_contents_for(full_path, expanding)
   for _, browser in pairs(pm.browsers) do
     if browser.matches(full_path[1]) then
@@ -86,44 +25,22 @@ function pm.get_contents_for(full_path, expanding)
   end
 end
 
----
--- Performs an action based on the selected treeview item.
--- This function is called internally and shouldn't be called by a script.
--- @param selected_item Identical to 'full_path' in pm.get_contents_for.
--- @see pm.get_contents_for
+-- LuaDoc is in core/.browser.lua.
 function pm.perform_action(selected_item)
   current_browser.perform_action(selected_item)
 end
 
----
--- Creates a context menu based on the selected treeview item.
--- This function is called internally and shouldn't be called by a script.
--- @param selected_item Identical to 'full_path' in pm.get_contents_for.
--- @return table of menu items.
---   The return table consists of an ordered list of strings to be used to
---   construct a context menu. The strings are handled as follows:
---     'gtk-*' - a stock menu item is created based on the GTK stock-id.
---     'separator' - a menu separator item is created.
---     Otherwise a regular menu item with a mnemonic is created.
--- @see pm.get_contents_for
+-- LuaDoc is in core/.browser.lua.
 function pm.get_context_menu(selected_item)
   return current_browser.get_context_menu(selected_item)
 end
 
----
--- Performs an action based on the selected menu item.
--- This function is called internally and shouldn't be called by a script.
--- @param menu_id The numeric ID of the menu item.
--- @param selected_item Identical to 'full_path' in pm.get_contents_for.
--- @see pm.get_contents_for
+-- LuaDoc is in core/.browser.lua.
 function pm.perform_menu_action(menu_id, selected_item)
   current_browser.perform_menu_action(menu_id, selected_item)
 end
 
----
--- Toggles the width of the project manager.
--- If the pm is visible, it's width is saved and then set to 0, effectively
--- hiding it. If it is hidden, the width is restored.
+-- LuaDoc is in core/.browser.lua.
 function pm.toggle_visible()
   if pm.width > 0 then
     pm.prev_width = pm.width
diff --git a/core/init.lua b/core/init.lua
index b6d04424..5039fe56 100644
--- a/core/init.lua
+++ b/core/init.lua
@@ -30,12 +30,7 @@ end
 
 rawset = nil -- do not allow modifications which could compromise stability
 
----
--- Checks if the buffer being indexed is the currently focused buffer.
--- This is necessary because any buffer actions are performed in the focused
--- views' buffer, which may not be the buffer being indexed. Throws an error
--- if the check fails.
--- @param buffer The buffer in question.
+-- LuaDoc is in core/.textadept.lua.
 function textadept.check_focused_buffer(buffer)
   if type(buffer) ~= 'table' or not buffer.doc_pointer then
     error(locale.ERR_BUFFER_EXPECTED, 2)
@@ -44,16 +39,7 @@ function textadept.check_focused_buffer(buffer)
   end
 end
 
----
--- Helper function for printing messages to buffers.
--- Splits the view and opens a new buffer for printing messages. If the message
--- buffer is already open and a view is currently showing it, the message is
--- printed to that view. Otherwise the view is split, goes to the open message
--- buffer, and prints to it.
--- @param buffer_type String type of message buffer.
--- @param ... Message strings.
--- @usage textadept._print(locale.ERROR_BUFFER, error_message)
--- @usage textadept._print(locale.MESSAGE_BUFFER, message)
+-- LuaDoc is in core/.textadept.lua.
 function textadept._print(buffer_type, ...)
   local function safe_print(...)
     local message = table.concat({...}, '\t')
@@ -88,20 +74,10 @@ function textadept._print(buffer_type, ...)
   pcall(safe_print, ...) -- prevent endless loops if this errors
 end
 
----
--- Prints messages to the Textadept message buffer.
--- Opens a new buffer (if one hasn't already been opened) for printing messages.
--- @param ... Message strings.
+-- LuaDoc is in core/.textadept.lua.
 function textadept.print(...) textadept._print(locale.MESSAGE_BUFFER, ...) end
 
----
--- Displays a CocoaDialog of a specified type with given arguments returning
--- the result.
--- @param kind The CocoaDialog type.
--- @param opts A table of key, value arguments. Each key is a --key switch with
---   a "value" value. If value is nil, it is omitted and just the switch is
---   used.
--- @return string CocoaDialog result.
+-- LuaDoc is in core/.textadept.lua.
 function cocoa_dialog(kind, opts)
   local args = { kind }
   for k, v in pairs(opts) do