Documentation overhaul.

1 files changed, 162 insertions, 96 deletions

diff --git a/core/events.lua b/core/events.lua
index 61ebd3ea..2b3db461 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -4,109 +4,173 @@ local textadept = _G.textadept
 local locale = _G.locale
 
 ---
--- Module that handles Scintilla and Textadept notifications/events.
--- Most of Textadept's functionality comes through handlers. Scintilla
--- notifications, Textadept's own events, and user-defined events can all be
--- handled.
+-- Textadept's core event structure and handlers.
 module('textadept.events', package.seeall)
 
--- Usage:
--- Each event can have multiple handlers, which are simply Lua functions that
--- are called in the sequence they are added as handler functions. Sometimes it
--- is useful to have a handler run under a specific condition(s). If this is the
--- case, place a conditional in the function that returns if it isn't met.
+-- Markdown:
+-- ## Overview
 --
--- If a handler returns either true or false explicitly, all subsequent handlers
--- are not called. This is useful for something like a 'keypress' event where if
--- the key is handled, true should be returned so as to not propagate the event.
+-- Textadept is very event-driven. Most of its functionality comes through event
+-- handlers. Events occur when you create a new buffer, press a key, click on a
+-- menu, etc. You can even make an event occur with Lua code. Instead of having
+-- a single event handler however, each event can have a set of handlers. These
+-- handlers are simply Lua functions that are called in the order they were
+-- added to an event. This enables dynamically loaded modules to add their own
+-- handlers to events.
 --
--- Events need not be declared. A handler can simply be added for an event name,
--- and 'handle'd when necessary. As an example, you can create a handler for a
--- custom 'my_event' and call "textadept.events.handle('my_event')" to envoke
--- it.
+-- Events themselves are nothing special. They do not have to be declared in
+-- order to be used. They are simply strings containing an arbitrary event name.
+-- When an event of this name occurs, either generated by Textadept or you, all
+-- event handlers assigned to it are run.
 --
--- For reference, events will be shown in 'event(arguments)' format, but in
--- reality, the event is handled as 'handle(event, arguments)'.
+-- Events can be given any number of arguments. These arguments will be passed
+-- to the event's handler functions. If a handler returns either true or false
+-- explicitly, all subsequent handlers are not called. This is useful if you
+-- want to stop the propagation of an event like a keypress.
 --
--- Scintilla notifications:
---   char_added(ch)
---     ch: the (integer) character added.
---   save_point_reached()
---   save_point_left()
---   double_click(position, line)
---     position: the position of the beginning of the line clicked.
---     line: the line clicked.
---   update_ui()
---   margin_click(margin, modifiers, position)
---     margin: the margin number.
---     modifiers: mouse modifiers.
---     position: the position of the beginning of the line at the point clicked.
---   user_list_selection(wParam, text)
---     wParam: the user list ID.
---     text: the text of the selected item.
---   uri_dropped(text)
---     text: the URI dropped.
---   call_tip_click(position)
---     position: 1 or 2 if the up or down arrow was clicked; 0 otherwise.
---   auto_c_selection(lParam, text)
---     lParam: the start position of the word being completed.
---     text: the text of the selected item.
+-- ## Textadept Events
 --
--- Textadept events:
---   buffer_new()
---   buffer_deleted()
---   buffer_before_switch()
---   buffer_after_switch()
---   view_new()
---   view_before_switch()
---   view_after_switch()
---   quit()
---     Note: when adding a quit handler, it must be inserted at index 1 because
---     the default quit handler returns true, which ignores all subsequent
---     handlers.
---   keypress(code, shift, control, alt)
---     code: the key code.
---     shift: flag indicating whether or not shift is pressed.
---     control: flag indicating whether or not control is pressed.
---     alt: flag indicating whether or not alt is pressed.
---   menu_clicked(menu_id)
---     menu_id: the numeric ID of the menu item.
---   pm_contents_request(full_path, expanding)
---     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).
---     expanding: indicates if the contents of a parent are being requested.
---   pm_item_selected(selected_item, gdkevent)
---     selected_item: identical to 'full_path' for 'pm_contents_request' event.
---     gdkevent: the GDK event associated with the request. It must be passed to
---       pm.show_context_menu()
---   pm_context_menu_request(selected_item)
---     selected_item: identical to 'full_path' for 'pm_contents_request' event.
---   pm_menu_clicked(menu_id, selected_item)
---     menu_id: the numeric ID for the menu item.
---     selected_item: identical to 'full_path' for 'pm_contents_request' event.
---   pm_view_filled()
---   find(text, next)
---     text: the text to find.
---     next: flag indicating whether or not the search direction is forward.
---   replace(text)
---     text: the text to replace the current selection 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.
---   replace_all(find_text, repl_text)
---     find_text: the text to find.
---     repl_text: the text to replace found text with.
---   find_keypress(code)
---     code: the key code.
---   command_entry_completions_request()
---   command_entry_keypress(code)
---     code: the key code.
+-- The following is a list of all Scintilla events generated by Textadept in
+-- `event_name(arguments)` format:
+--
+-- * **char\_added** (ch)<br />
+--   Called when an ordinary text character is added to the buffer.
+--       - ch: the ASCII representation of the character.
+-- * **save\_point\_reached** ()<br />
+--   Called when a save point is entered.
+-- * **save\_point\_left** ()<br />
+--   Called when a save point is left.
+-- * **double\_click** (position, line)<br />
+--   Called when the mouse button is double-clicked.
+--       - position: the text position the click occured at.
+--       - line: the line number the click occured at.
+-- * **update\_ui** ()<br />
+--   Called when the text or styling of the buffer has changed or the selection
+--   range has changed.
+-- * **margin\_click** (margin, modifiers, position)<br />
+--   Called when the mouse is clicked inside a margin.
+--       - margin: the margin number that was clicked.
+--       - modifiers: the appropriate combination of `SCI_SHIFT`, `SCI_CTRL`,
+--         and `SCI_ALT` to indicate the keys that were held down at the time of
+--         the margin click.
+--       - position: The position of the start of the line in the buffer that
+--         corresponds to the margin click.
+-- * **user\_list\_selection** (wParam, text)<br />
+--   Called when the user has selected an item in a user list.
+--       - wParam: the list_type parameter from
+--         [`buffer:user_list_show()`][buffer_user_list_show].
+--       - text: the text of the selection.
+-- * **uri\_dropped** (text)<br />
+--   Called when the user has dragged a URI such as a file name or web address
+--   into Textadept.
+--       - text: URI text.
+-- * **call\_tip\_click** (position)<br />
+--   Called when the user clicks on a calltip.
+--       - position: 1 if the click is in an up arrow, 2 if in a down arrow, and
+--         0 if elsewhere.
+-- * **auto\_c\_selection** (lParam, text)<br />
+--   Called when the user has selected an item in an autocompletion list.
+--       - lParam: the start position of the word being completed.
+--       - text: the text of the selection.
+--
+-- [buffer_user_list_show]: ../modules/buffer.html#buffer:user_list_show
+--
+-- The following is a list of all Textadept events generated in
+-- `event_name(arguments)` format:
+--
+-- * **buffer\_new** ()<br />
+--   Called when a new [buffer][buffer] is created.
+-- * **buffer\_deleted** ()<br />
+--   Called when a [buffer][buffer] has been deleted.
+-- * **buffer\_before\_switch** ()<br />
+--   Called right before another [buffer][buffer] is switched to.
+-- * **buffer\_after\_switch** ()<br />
+--   Called right after a [buffer][buffer] was switched to.
+-- * **view\_new** ()<br />
+--   Called when a new [view][view] is created.
+-- * **view\_before\_switch** ()<br />
+--   Called right before another [view][view] is switched to.
+-- * **view\_after\_switch** ()<br />
+--   Called right after [view][view] was switched to.
+-- * **quit** ()<br />
+--   Called when quitting Textadept.<br />
+--   Note: Any quit handlers added must be inserted at index 1 because the
+--   default quit handler in `core/events.lua` returns `true`, which ignores all
+--   subsequent handlers.
+-- * **keypress** (code, shift, control, alt)<br />
+--   Called when a key is pressed.
+--       - code: the key code (according to `<gdk/gdkkeysyms.h>`).
+--       - shift: flag indicating whether or not the Shift key is pressed.
+--       - control: flag indicating whether or not the Control key is pressed.
+--       - alt: flag indicating whether or not the Alt/Apple key is pressed.
+--   <br />
+--   Note: The Alt-Option key in Mac OSX is not available.
+-- * **menu\_clicked** (menu\_id)<br />
+--   Called when a menu item is selected.
+--       - menu\_id: the numeric ID of the menu item set in
+--         [`textadept.gtkmenu()`][textadept_gtkmenu].
+-- * **pm\_contents\_request** (full\_path, expanding)<br />
+--   Called when the [PM][PM] requests data to display.
+--       - full\_path: a numerically indexed table of treeview item parents. The
+--         first index contains the text of the PM entry. Subsequent indices
+--         contain the ID's of parents of the child (if any).
+--       - expanding: indicates if the contents of a parent are being requested.
+-- * **pm\_item\_selected** (selected\_item)<br />
+--   Called when an item in the [PM][PM] is double-clicked or activated.
+--       - selected\_item: identical to `full_path` in the `pm_contents_request`
+--         event.
+-- * **pm\_context\_menu\_request** (selected\_item, gdkevent)<br />
+--   Called when the context menu for an item in the [PM][PM] is requested.
+--       - selected\_item: identical to `full_path` in the `pm_contents_request`
+--         event.
+--       - gdkevent: the GDK event associated with the request. It must be
+--         passed to [`textadept.pm.show_context_menu()`][pm_show_menu].
+-- * **pm\_menu\_clicked** (menu\_id, selected\_item)<br />
+--   Called when a [PM][PM] context menu item is selected.
+--       - menu\_id: the numeric ID of the context menu item set in
+--         [`textadept.gtkmenu()`][textadept_gtkmenu].
+--       - selected\_item: identical to `full_path` in the `pm_contents_request`
+--         event.
+-- * **pm\_view\_filled** ()<br />
+--   Called when the [PM][PM] view is filled with data.
+-- * **find** (text, next)<br />
+--   Called when attempting to finding text via the Find dialog box.
+--       - text: the text to search for.
+--       - next: flat indicating whether or not the search direction is forward.
+-- * **replace** (text)<br />
+--   Called when the found text is selected and asked to be replaced.
+--       - text: the text to replace the selected text with.
+-- * **replace\_all** (find\_text, repl\_text)<br />
+--   Called when all occurances of found text are to be replaced.
+--       - find\_text: the text to search for.
+--       - repl\_text: the text to replace found text with.
+-- * **command\_entry\_keypress** (code)<br />
+--   Called when a key is pressed in the Command Entry.
+--       - code: the key code (according to `<gdk/gdkkeysyms.h>`).
+--
+-- [buffer]: ../modules/buffer.html
+-- [view]: ../modules/view.html
+-- [textadept_gtkmenu]: ../modules/textadept.html#gtkmenu
+-- [PM]: ../modules/textadept.pm.html
+-- [pm_show_menu]: ../modules/textadept.pm.html#show_context_menu
+--
+-- ## Example
+--
+-- The following Lua code generates and handles a custom `my_event` event:
+--
+--     function my_event_handler(message)
+--       textadept.print(message)
+--     end
+--
+--     textadept.events.add_handler('my_event', my_event_handler)
+--     textadept.events.handle('my_event', 'my message')
 
 local events = textadept.events
 
 ---
 -- Adds a handler function to an event.
--- @param event The string event name.
+-- @param event The string event name. It is arbitrary and need not be defined
+--   anywhere.
 -- @param f The Lua function to add.
 -- @param index Optional index to insert the handler into.
 function add_handler(event, f, index)
@@ -121,12 +185,13 @@ function add_handler(event, f, index)
 end
 
 ---
--- Calls every handler function added to an event in sequence.
--- If true or false is returned by any handler, the iteration ceases. Normally
--- this function is called by the system when necessary, but it can be called
--- in scripts to handle user-defined events.
+-- Calls all handlers for the given event in sequence (effectively "generating"
+-- the event).
+-- If true or false is explicitly returned by any handler, the event is not
+-- propagated any further; iteration ceases.
 -- @param event The string event name.
--- @param ... Arguments to the handler.
+-- @param ... Arguments passed to the handler.
+-- @return true or false if any handler explicitly returned such; nil otherwise.
 function handle(event, ...)
   local plural = event..'s'
   local handlers = events[plural]
@@ -155,6 +220,7 @@ local scnnotifications = {
 ---
 -- Handles Scintilla notifications.
 -- @param n The Scintilla notification structure as a Lua table.
+-- @return true or false if any handler explicitly returned such; nil otherwise.
 function notification(n)
   local f = scnnotifications[n.code]
   if f then