-- Copyright 2007-2013 Mitchell mitchell.att.foicica.com. See LICENSE.
-- This is a DUMMY FILE used for making LuaDoc for built-in functions in the
-- global _M table.

--[[ This comment is for LuaDoc.
---
-- A table of loaded modules.
--
-- ## Module Guidelines
--
-- At the very least, modules consist of a single directory with an *init.lua*
-- script. However, the script may load additional Lua files present in the
-- directory. (For an example, see *modules/textadept/init.lua*.)
--
-- Loaded modules, regardless of whether they are generic or language-specific,
-- persist in Textadept's Lua State; Textadept never unloads them. Therefore,
-- modules should define functions or variables within the module itself, not
-- globally.
--
-- ### Language-Specific
--
-- To fully take advantage of Textadept's features, language-specific modules
-- should have at a minimum: a block comment string, run and/or compile
-- commands, an event handler for setting buffer properties like indentation,
-- and if possible, an Adeptsense. Optional features are extra snippets and
-- commands and a context menu.
--
-- #### Block Comment
--
-- The `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in curses) key binding toggles code
-- comments. In order for this to work for your language, the
-- [`_M.textadept.editing.comment_string`][] table must have a key with the
-- language's lexer name assigned to a comment prefix string. For Lua, it would
-- look like
--
--     _M.textadept.editing.comment_string.lua = '--'
--
-- [`_M.textadept.editing.comment_string`]: _M.textadept.editing.html#comment_string
--
-- #### Compile and Run
--
-- The `Ctrl+Shift+R` and `Ctrl+R` (`⌘⇧R` and `⌘R` on Mac OSX | `M-^R` and `^R`
-- in curses) key bindings compile and run code, respectively. In order for
-- these to work for your language, the [`_M.textadept.run.compile_command`][]
-- and [`_M.textadept.run.run_command`][] tables must have keys with the
-- language's lexer name assigned to compile and run shell commands,
-- respectively. Commands may contain [macros][]. For Lua, it would look like
--
--     _M.textadept.run.compile_command.lua = 'luac %(filename)'
--     _M.textadept.run.run_command = 'lua %(filename)'
--
-- The module should also define error details in
-- [`_M.textadept.run.error_detail`][] so double-clicking on compile or runtime
-- errors jumps to the error's location. The format for Lua errors looks like
--
--     _M.textadept.run.error_detail.lua = {
--       pattern = '^lua: (.-):(%d+): (.+)$',
--       filename = 1, line = 2, message = 3
--     }
--
-- [`_M.textadept.run.compile_command`]: _M.textadept.run.html#compile_command
-- [`_M.textadept.run.run_command`]: _M.textadept.run.html#run_command
-- [macros]: _M.textadept.run.html#execute
-- [`_M.textadept.run.error_detail`]: _M.textadept.run.html#error_detail
--
-- #### Buffer Properties
--
-- By default, Textadept uses 2 spaces as indentation. If your language has
-- different indentation guidelines, change them from an
-- `events.LANGUAGE_MODULE_LOADED` event handler. Using tabs of width 8 would
-- look like
--
--     events.connect(events.LANGUAGE_MODULE_LOADED, function(lang)
--       if lang == 'lua' then
--         buffer.tab_width = 8
--         buffer.use_tabs = true
--       end
--     end
--
-- #### Adeptsense
--
-- The `Ctrl+Space` and `Ctrl+H` (`⌥⎋` and `^H` on Mac OSX | `^Space` and `M-H`
-- or `M-S-H` in curses) key bindings autocomplete symbols and show API
-- documentation, respectively, when editing code. In order for these to work
-- for your language, you must create an [Adeptsense][].
--
-- [Adeptsense]: _M.textadept.adeptsense.html
--
-- #### Snippets
--
-- [Snippets][] for common language constructs are useful. Some snippets for
-- common Lua control structures look like
--
--     snippets.lua = {
--       f = "function %1(name)(%2(args))\n\t%0\nend",
--       ['for'] = "for i = %1(1), %2(10)%3(, -1) do\n\t%0\nend",
--       fori = "for %1(i), %2(val) in ipairs(%3(table)) do\n\t%0\nend",
--       forp = "for %1(k), %2(v) in pairs(%3(table)) do\n\t%0\nend",
--     }
--
-- [Snippets]: _M.textadept.snippets.html
--
-- #### Commands
--
-- Additional editing features for the language can be useful. For example, the
-- [Lua][] module has a feature to autocomplete the `end` keyword in a control
-- structure and the [C/C++][] module has a feature to add a ';' to the end of
-- the current line and insert a new line. Both are bound to the `Shift+Enter`
-- (`⇧↩` on Mac OSX | `S-Enter` in curses) key for easy access.
--
--     -- In file *lua/init.lua*             | -- In file *cpp/init.lua*
--                                           |
--     function M.try_to_autocomplete_end()  | keys.cpp = {
--       ...                                 |   ['s\n'] = function()
--     end                                   |     buffer:line_end()
--                                           |     buffer:add_text(';')
--     keys.lua = {                          |     buffer:new_line()
--       ['s\n'] = M.try_to_autocomplete_end |   end
--     }                                     | }
--
-- [Lua]: _M.lua.html
-- [C/C++]: _M.cpp.html
--
-- #### Context Menu
--
-- Language-specific [context menus][], accessible by right-clicking inside the
-- view, are useful for accessing module features without using key bindings.
-- For Lua this might look like
--
--     M.context_menu = {
--       { _L['_Undo'], buffer.undo },
--       { _L['_Redo'], buffer.redo },
--       { '' },
--       { _L['Cu_t'], buffer.cut },
--       { _L['_Copy'], buffer.copy },
--       { _L['_Paste'], buffer.paste },
--       { _L['_Delete'], buffer.clear },
--       { '' },
--       { _L['Select _All'], buffer.select_all },
--       { '' },
--       { 'Autocomplete "end"', M.try_to_autocomplete_end }
--     }
--
-- [context menus]: _M.textadept.menu.html#set_contextmenu
module('_M')]]