-- 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 can load additional Lua files present in the
-- directory. (For an example, see *modules/textadept/init.lua*.)
--
-- Once modules are loaded, regardless of whether they are generic or
-- language-specific, they persist in Textadept's Lua State; they are never
-- unloaded. Therefore, modules should not set global functions or variables in
-- order to avoid polluting the global environment. All functions and variables
-- should be contained within the module.
--
-- ### 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, a buffer property setter function, 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 will jump 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 in a `set_buffer_properties()`
-- function. Using tabs of width 8 would look like
--
--     function M.set_buffer_properties()
--       buffer.tab_width = 8
--       buffer.use_tabs = true
--     end
--
-- This function is called automatically to set the properties for the
-- language's source files.
--
-- #### 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 can be 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.
--
--     function M.try_to_autocomplete_end()
--       ...
--     end
--
--     keys.lua = {
--       ['s\n'] = M.try_to_autocomplete_end
--     }
--
-- ---
--
--     keys.cpp = {
--       ['s\n'] = function()
--         buffer:line_end()
--         buffer:add_text(';')
--         buffer:new_line()
--       end
--     }
--
-- [Lua]: _M.lua.html
-- [C/C++]: _M.cpp.html
--
-- #### Context Menu
--
-- Language-specific [context menus][], accessible by right-clicking inside the
-- view, can be useful for accessing module features without using key bindings.
-- For Lua this may 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')]]