Rewrote LuaDoc.

1 files changed, 29 insertions, 22 deletions

diff --git a/core/init.lua b/core/init.lua
index e0efd459..8ac2dade 100644
--- a/core/init.lua
+++ b/core/init.lua
@@ -23,16 +23,16 @@ _M = {} -- modules table
 ---
 -- Extends Lua's _G table to provide extra functions and fields for Textadept.
 -- @field _HOME (string)
---   Path to the directory containing Textadept.
+--   The path to the directory containing Textadept.
 -- @field _LEXERPATH (string)
---   Paths to lexers, formatted like [`package.path`][].
+--   The paths to lexers, formatted like Lua's [`package.path`][].
 --
 --   [`package.path`]: http://lua.org/manual/5.2/manual.html#pdf-package.path
 -- @field _RELEASE (string)
---   The Textadept release version.
+--   The Textadept release version string.
 -- @field _USERHOME (string)
---   Path to the user's *~/.textadept/*, where all preferences and user-data is
---   stored.
+--   The path to the user's *~/.textadept/* directory, where all preferences and
+--   user-data is stored.
 --   On Windows machines *~/* is the value of the "USERHOME" environment
 --   variable, typically *C:\Users\username\\* or
 --   *C:\Documents and Settings\username\\*. On Linux, BSD, and Mac OSX
@@ -53,16 +53,12 @@ _M = {} -- modules table
 --   ncurses feature incompatibilities are listed in the [Appendix][].
 --
 --   [Appendix]: ../14_Appendix.html#Ncurses.Compatibility
--- @field buffer The current [buffer][] in the current [view](#view).
---
--- [buffer]: buffer.html
--- @field view The currently focused [view](view.html).
 module('_G')]]
 
 --[[ The tables below were defined in C.
 
 ---
--- Command line parameters passed to Textadept.
+-- Table of command line parameters passed to Textadept.
 -- @class table
 -- @see _G.args
 -- @name arg
@@ -73,8 +69,8 @@ local arg
 -- Numeric keys have buffer values and buffer keys have their associated numeric
 -- keys.
 -- @class table
--- @usage _BUFFERS[1] contains the first buffer.
--- @usage _BUFFERS[buffer] returns the index of the current buffer in _BUFFERS.
+-- @usage _BUFFERS[n]      --> buffer at index n
+-- @usage _BUFFERS[buffer] --> index of buffer in _BUFFERS
 -- @see _G.buffer
 -- @name _BUFFERS
 local _BUFFERS
@@ -84,16 +80,28 @@ local _BUFFERS
 -- Numeric keys have view values and view keys have their associated numeric
 -- keys.
 -- @class table
--- @usage _VIEWS[1] contains the first view.
--- @usage _VIEWS[view] returns the index of the current view in _VIEWS.
+-- @usage _VIEWS[n]    --> view at index n
+-- @usage _VIEWS[view] --> index of view in _VIEWS
 -- @see _G.view
 -- @name _VIEWS
 local _VIEWS
 
+---
+-- The current [buffer](buffer.html) in the current [view](#view).
+-- @class table
+-- @name buffer
+local buffer
+
+---
+-- The currently focused [view](view.html).
+-- @class table
+-- @name view
+local view
+
 -- The functions below are Lua C functions.
 
 ---
--- Creates a new buffer.
+-- Creates and returns a new buffer.
 -- Emits a `BUFFER_NEW` event.
 -- @return the new buffer.
 -- @class function
@@ -102,16 +110,15 @@ local _VIEWS
 local new_buffer
 
 ---
--- Quits Textadept.
--- Emits a `QUIT` event. If any handler returns `false`, Textadept does not
--- quit.
+-- Emits a `QUIT` event, and unless any handler returns `false`, quits
+-- Textadept.
 -- @see events.QUIT
 -- @class function
 -- @name quit
 local quit
 
 ---
--- Resets the Lua state by reloading all init scripts.
+-- Resets the Lua state by reloading all initialization scripts.
 -- Language-specific modules for opened files are NOT reloaded. Re-opening the
 -- files that use them will reload those modules instead.
 -- This function is useful for modifying user scripts (such as
@@ -125,9 +132,9 @@ local quit
 local reset
 
 ---
--- Calls a given function after an interval of time.
--- To repeatedly call the function, return `true` inside the function. A `nil`
--- or `false` return value stops repetition.
+-- Calls the function *f* with the given arguments after *interval* seconds and
+-- then repeatedly while *f* returns `true`. A `nil` or `false` return value
+-- stops repetition.
 -- @param interval The interval in seconds to call the function after.
 -- @param f The function to call.
 -- @param ... Additional arguments to pass to `f`.