From 9bff1b29293b50e506936e93c14d7a65e8b0ea29 Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Fri, 6 Sep 2013 23:42:13 -0400 Subject: Updated LuaDoc. --- core/.iconv.luadoc | 12 ++++++------ core/.view.luadoc | 5 +++-- core/events.lua | 57 +++++++++++++++++++++++++----------------------------- core/file_io.lua | 4 ++-- core/keys.lua | 4 ++-- core/lfs_ext.lua | 2 +- core/ui.lua | 8 ++++---- 7 files changed, 44 insertions(+), 48 deletions(-) (limited to 'core') diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc index e8892c20..ee403194 100644 --- a/core/.iconv.luadoc +++ b/core/.iconv.luadoc @@ -6,9 +6,9 @@ module('string') --- --- Converts string *text* from character set *from* to character set *to* using --- iconv. --- Valid character sets are [GNU iconv's character sets][] and include: +-- Converts string *text* from encoding *from* to encoding *to* using iconv, +-- returning the string result. +-- Valid encodings are [GNU iconv's encodings][] and include: -- -- * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U, -- KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131}, @@ -31,8 +31,8 @@ module('string') -- * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16, -- UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA. -- --- [GNU iconv's character sets]: http://www.gnu.org/software/libiconv/ +-- [GNU iconv's encodings]: http://www.gnu.org/software/libiconv/ -- @param text The text to convert. --- @param to The string character set to convert to. --- @param from The string character set to convert from. +-- @param to The string encoding to convert to. +-- @param from The string encoding to convert from. function iconv(text, to, from) end diff --git a/core/.view.luadoc b/core/.view.luadoc index 949ee997..29509f9b 100644 --- a/core/.view.luadoc +++ b/core/.view.luadoc @@ -5,7 +5,8 @@ --- -- A Textadept view object. -- @field size (number) --- The position of the split resizer (if this view is part of a split view). +-- The pixel position of the split resizer if this view is part of a split +-- view. module('view') --- @@ -15,7 +16,7 @@ module('view') local buffer --- --- Splits the view into top and bottom views, unless *vertical* is `true`, +-- Splits the view into top and bottom views unless *vertical* is `true`, -- focuses the new view, and returns both the old and new views. -- If *vertical* is `false`, splits the view vertically into left and -- right views. diff --git a/core/events.lua b/core/events.lua index 658d011b..b7b9771d 100644 --- a/core/events.lua +++ b/core/events.lua @@ -29,7 +29,7 @@ local M = {} -- handler handled it. -- -- @field APPLEEVENT_ODOC (string) --- Emitted when Mac OSX tells Textadept to open a document. +-- Emitted when Mac OSX tells Textadept to open a file. -- Arguments: -- -- * _`uri`_: The UTF-8-encoded URI to open. @@ -45,8 +45,7 @@ local M = {} -- Arguments: -- -- * _`text`_: The text of the selection. --- * _`position`_: The position in the buffer of the beginning of the --- autocompleted word. +-- * _`position`_: The position of the beginning of the autocompleted word. -- @field BUFFER_AFTER_SWITCH (string) -- Emitted right after switching to another buffer. -- Emitted by [`view:goto_buffer()`][]. @@ -86,9 +85,8 @@ local M = {} -- -- * _`position`_: The position in the buffer double-clicked. -- * _`line`_: The line number double-clicked. --- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are --- `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and --- `buffer.SCMOD_META`. +-- * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`, +-- `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both* -- "Control" and "Alt" due to a Scintilla limitation with GTK+. @@ -123,9 +121,8 @@ local M = {} -- Arguments: -- -- * _`position`_: The position in the buffer clicked. --- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are --- `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and --- `buffer.SCMOD_META`. +-- * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`, +-- `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both* -- "Control" and "Alt" due to a Scintilla limitation with GTK+. @@ -135,9 +132,8 @@ local M = {} -- Arguments: -- -- * _`position`_: The position in the buffer double-clicked. --- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are --- `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and --- `buffer.SCMOD_META`. +-- * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`, +-- `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both* -- "Control" and "Alt" due to a Scintilla limitation with GTK+. @@ -148,22 +144,21 @@ local M = {} -- -- * _`position`_: The position in the buffer unclicked. -- @field INDICATOR_CLICK (string) --- Emitted when clicking the mouse on text that has an indicator. +-- Emitted when clicking the mouse on text that has an indicator present. -- Arguments: -- --- * _`position`_: The position in the buffer clicked. --- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are --- `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and --- `buffer.SCMOD_META`. +-- * _`position`_: The position of the clicked text in the buffer. +-- * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`, +-- `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both* -- "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field INDICATOR_RELEASE (string) --- Emitted after releasing the mouse after clicking on text that had an --- indicator. +-- Emitted when releasing the mouse after clicking on text that has an +-- indicator present. -- Arguments: -- --- * _`position`_: The position in the buffer unclicked. +-- * _`position`_: The position of the clicked text in the buffer. -- @field INITIALIZED (string) -- Emitted after Textadept finishes initializing. -- @field KEYPRESS (string) @@ -182,10 +177,9 @@ local M = {} -- -- * _`margin`_: The margin number clicked. -- * _`position`_: The position of the start of the line in the buffer whose --- margin line was clicked. --- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are --- `buffer.SCMOD_ALT`, `buffer.SCMOD_CTRL`, `buffer.SCMOD_SHIFT`, and --- `buffer.SCMOD_META`. +-- margin was clicked. +-- * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.SCMOD_CTRL`, +-- `buffer.SCMOD_SHIFT`, `buffer.SCMOD_ALT`, and `buffer.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `buffer.SCMOD_CTRL`, the "Control" modifier is reported as *both* -- "Control" and "Alt" due to a Scintilla limitation with GTK+. @@ -261,9 +255,10 @@ module('events')]] local handlers = {} --- --- Adds function *f* to the set of event handlers for *event* at position --- *index*, returning a handler ID for *f*. *event* is an arbitrary event name --- that does not need to have been previously defined. +-- Adds function *f* to the set of event handlers for event *event* at position +-- *index*, returning the handler identifier for *f*. +-- *event* may be any arbitrary string and does not need to have been previously +-- defined. -- @param event The string event name. -- @param f The Lua function to connect to *event*. -- @param index Optional index to insert the handler into. @@ -280,8 +275,8 @@ function M.connect(event, f, index) end --- --- Removes handler ID *id*, returned by `events.connect()`, from the set of --- event handlers for *event*. +-- Removes handler identifier *id*, returned by `events.connect()`, from the set +-- of handlers for event *event*. -- @param event The string event name. -- @param id ID of the handler returned by `events.connect()`. -- @see connect @@ -293,9 +288,9 @@ end local error_emitted = false --- --- Sequentially calls all handler functions for *event* with the given +-- Sequentially calls all handler functions for event *event* with the given -- arguments. --- *event* is an arbitrary event name that does not need to have been previously +-- *event* may be any arbitrary string and does not need to have been previously -- defined. If any handler explicitly returns `true` or `false`, the event is -- not propagated any further, iteration ceases, and `emit()` returns that -- value. This is useful for stopping the propagation of an event like a diff --git a/core/file_io.lua b/core/file_io.lua index 2cf7f08b..967332f8 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -79,7 +79,7 @@ io.SNAPOPEN_MAX = 1000 io.recent_files = {} --- --- List of byte-order marks (BOMs) for identifying unicode file types. +-- List of byte-order marks (BOMs) for identifying unicode file encodings. -- @class table -- @name boms io.boms = { @@ -89,7 +89,7 @@ io.boms = { } --- --- List of encodings to try to decode files as. +-- List of encodings to attempt to decode files as. -- You should add to this list if you get a "Conversion failed" error when -- trying to open a file whose encoding is not recognized. Valid encodings are -- [GNU iconv's encodings][] and include: diff --git a/core/keys.lua b/core/keys.lua index 338c54e9..ac782df1 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -104,12 +104,12 @@ local M = {} -- c = {function3, arg1, arg2} -- } -- @field CLEAR (string) --- The string representing the key sequence that clears the current key chain. +-- The key that clears the current key chain. -- It cannot be part of a key chain. -- The default value is `'esc'` for the `Esc` (`⎋` on Mac OSX | `Esc` in -- curses) key. -- @field LANGUAGE_MODULE_PREFIX (string) --- The starting key of the key chain reserved for language modules. +-- The prefix key of the key chain reserved for language modules. -- The default value is `'cl'` on platforms other than Mac OSX, `'ml'` -- otherwise. Equivalent to `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in curses). -- @field MODE (string) diff --git a/core/lfs_ext.lua b/core/lfs_ext.lua index d79800a4..36dfeffc 100644 --- a/core/lfs_ext.lua +++ b/core/lfs_ext.lua @@ -6,7 +6,7 @@ module('lfs')]] --- --- Filter table containing common binary file extensions and version control +-- The filter table containing common binary file extensions and version control -- folders to exclude when iterating over files and directories using -- `dir_foreach` when its `exclude_FILTER` argument is `false`. -- @see dir_foreach diff --git a/core/ui.lua b/core/ui.lua index d347d724..4ef4ea70 100644 --- a/core/ui.lua +++ b/core/ui.lua @@ -52,7 +52,7 @@ local function _print(buffer_type, ...) buffer:set_save_point() end --- --- Helper function for printing messages to buffers. +-- Helper function for printing messages to the buffer of type *buffer_type*. -- Splits the view and opens a new buffer for printing messages to. If the -- message buffer is already open in a view, the message is printed to that -- view. Otherwise the view is split and the message buffer is opened or @@ -383,7 +383,7 @@ events_connect(events.ERROR, ui.print) local menubar --- --- A table containing the width and height values of the Textadept window. +-- A table containing the width and height pixel values of the Textadept window. -- @class table -- @name size local size @@ -391,8 +391,8 @@ local size The functions below are Lua C functions. --- --- Displays a *kind* [gtdialog][] with the given string arguments to pass to --- the dialog and returns a formatted string of the dialog's output. +-- Displays a [gtdialog][] of kind *kind* with the given string arguments to +-- pass to the dialog and returns a formatted string of the dialog's output. -- Table arguments containing strings are allowed and expanded in place. This is -- useful for filtered list dialogs with many items. -- For more information on gtdialog, see [http://foicica.com/gtdialog][]. -- cgit v1.2.3