From 3c297a7b08ade12ee73541a24762a30b7b3c2c9d Mon Sep 17 00:00:00 2001 From: Chris Mann Date: Sun, 7 Sep 2008 20:39:24 +0930 Subject: [PATCH] * wesnoth-mode.el: Documentation clean-up aided by `checkdoc'. --- wesnoth-mode.el | 80 ++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 48 insertions(+), 32 deletions(-) diff --git a/wesnoth-mode.el b/wesnoth-mode.el index c76c320..e2f711b 100644 --- a/wesnoth-mode.el +++ b/wesnoth-mode.el @@ -1,4 +1,4 @@ -;; wesnoth-mode.el - A major mode for editing WML. +;;; wesnoth-mode.el --- A major mode for editing WML. ;; Copyright (C) 2006, 2007, 2008 Chris Mann ;; This program is free software; you can redistribute it and/or @@ -17,20 +17,20 @@ ;; MA 02139, USA. ;;; Description: -;; wesnoth-mode is a major mode for Emacs which assists in the editing -;; of Wesnoth Markup Language (WML) files. Currently, this mode -;; features syntax highlighting support, automatic indentation, -;; tag-completion and preliminary support for syntax checking. - -;;; Usage: -;; Add the following to your .emacs: -;; (add-to-list 'load-path "path/to/wesnoth-mode") -;; (autoload 'wesnoth-mode "wesnoth-mode" "Major mode for editing WML." t) -;; Optionally adding: -;; (add-to-list 'auto-mode-alist '("\\.cfg\\'" . wesnoth-mode)) -;; to automatically load wesnoth-mode for all files ending in '.cfg'. - -;;; Changes: +;; wesnoth-mode is a major mode for Emacs which assists in the editing +;; of Wesnoth Markup Language (WML) files. Currently, this mode +;; features syntax highlighting support, automatic indentation, +;; tag-completion and preliminary support for syntax checking. + +;;; Commentary: +;; Add the following to your .emacs: +;; (add-to-list 'load-path "path/to/wesnoth-mode") +;; (autoload 'wesnoth-mode "wesnoth-mode" "Major mode for editing WML." t) +;; Optionally adding: +;; (add-to-list 'auto-mode-alist '("\\.cfg\\'" . wesnoth-mode)) +;; to automatically load wesnoth-mode for all files ending in '.cfg'. + +;;; History: ;; 1.2.4 ;; * Improved syntax-highlighting for macro calls. ;; * Underscore is now treated as whitespace. @@ -92,8 +92,9 @@ ;; * Base indent now defaults to 4. ;; * Added support for #ifndef. +;;; Code: (defconst wesnoth-mode-version "1.2.4" - "The current version of wesnoth-mode.") + "The current version of `wesnoth-mode'.") (defgroup wesnoth-mode nil "Wesnoth-mode access" :group 'languages @@ -115,9 +116,7 @@ the same level." :group 'wesnoth-mode) (defcustom wesnoth-auto-indent-flag t - "Whether to attempt tag indentation when a newline is created. -If nil, no indentation will be attempted. Otherwise, attempt to -indent the line." + "Non-nil means indent the current line upon creating a newline." :type 'boolean :group 'wesnoth-mode) @@ -184,7 +183,7 @@ indent the line." (modify-syntax-entry ?\n ">" wesnoth-syntax-table) (modify-syntax-entry ?\r ">" wesnoth-syntax-table) wesnoth-syntax-table) - "Syntax table for wesnoth-mode.") + "Syntax table for `wesnoth-mode'.") ;; Prevents automatic syntax-highlighting of elements which might be ;; pre-processor statements. @@ -192,7 +191,7 @@ indent the line." (list '("\\(^[\t ]*\\(#\\(?:define \\|e\\(?:lse\\|nd\\(?:\\(?:de\\|i\\)f\\)\\)\\|\\(?:ifn?\\|un\\)def \\)\\)\\|#enddef\\)" 1 "w") '("\\(#[\t ]*.*$\\)" 1 "<")) - "Highlighting syntactic keywords within wesnoth-mode.") + "Highlighting syntactic keywords within `wesnoth-mode'.") (defun wesnoth-preprocessor-best-face () "Use `font-lock-preprocessor-face' when available." @@ -216,24 +215,33 @@ indent the line." '("\\$\\(\\w\\|_\\)+" . font-lock-variable-name-face) '("\\(\\(\\w\\|_\\)+\\(\\,[\t ]*\\(\\w\\|_\\)+\\)*\\)=" 1 font-lock-variable-name-face)) - "Syntax highlighting for wesnoth-mode.") + "Syntax highlighting for `wesnoth-mode'.") (defun wesnoth-element-closing (&optional all) - "Return string to use for a closing element." + "Return string to use for a closing element. + +If the optional argument ALL is non-nil, include all closing +preprocessor statements." (if (or (not wesnoth-indent-preprocessor-bol) all) (concat "^[ \t]*\\[/\\|" wesnoth-preprocessor-closing-regexp) "^[ \t]*\\(\\[/\\|#enddef\\)")) (defun wesnoth-element-opening (&optional all) - "Return string to use for an opening element." + "Return string to use for an opening element. + +If the optional argument ALL is non-nil, include all closing +preprocessor statements." (if (or (not wesnoth-indent-preprocessor-bol) all) (concat "^[ \t]*\\[[^/]\\|" wesnoth-preprocessor-opening-regexp) "^[ \t]*\\(\\[[^/]\\|#define\\)")) (defun wesnoth-element (&optional all) - "Return string to use for an opening or closing element." + "Return string to use for an opening or closing element. + +If the optional argument ALL is non-nil, include all preprocessor +statements." (if (or (not wesnoth-indent-preprocessor-bol) all) (concat "^[\t ]*\\[/?\\|" wesnoth-preprocessor-regexp) @@ -292,14 +300,14 @@ If REBUILD is non-nil, regenerate `wesnoth-completion-cache'." (setq wesnoth-completion-cache tags))))) (defun wesnoth-insert-tag (tagname &optional start end) - "Inserts the specified opening tag and it's matching closing tag. + "Insert the specified opening tag and it's matching closing tag. Both the opening and closing tags will be placed on their own lines with point positioned between them. Completion of tags at the prompt uses `wesnoth-tags-list'. TAGNAME is the name of the tag to be inserted. If START and END are given, the tags will be inserted around the specified region. -Enabling `transient-mark-mode' will cause `wesnoth-insert-tag' to +Enabling function `transient-mark-mode' will cause `wesnoth-insert-tag' to insert opening and closing tags around the specified region." (interactive (list (completing-read "Tag: " (wesnoth-build-completion) nil nil))) @@ -336,7 +344,7 @@ insert opening and closing tags around the specified region." "Insert the next expected closing element at point. START and END define the region to check for missing closing -elements. If `transient-mark-mode' is enabled, the region +elements. If function `transient-mark-mode' is enabled, the region specified will be used as START and END. Otherwise, START and END will be the minimum and maximum positions of the buffer, respectively." @@ -359,7 +367,9 @@ respectively." (error "%s" "Unable to find element to insert")))) (defun wesnoth-insert-and-indent (&rest args) - "Concatenate and insert the given string(s) before indenting." + "Concatenate and insert the given string(s) before indenting. + +ARGS is a list of strings to be inserted." (insert (apply 'concat args)) (wesnoth-indent) (end-of-line)) @@ -569,7 +579,10 @@ Creates and destroys a cache of macro definition details as necessary." (setq wesnoth-define-blocks nil))) (defun wesnoth-determine-context (position) - "Determine the type of the last relevant element." + "Determine the type of the last relevant element. + +POSITION is the buffer position of the element for which to +determine the context." (save-excursion (search-backward-regexp (wesnoth-element) (wesnoth-wml-start-pos) t) (let ((match (or (match-string 1) "")) @@ -592,7 +605,10 @@ Creates and destroys a cache of macro definition details as necessary." (defun wesnoth-newline-and-indent (&optional indent) "Indent both the current line and the newline created. If `wesnoth-auto-indent-flag' is nil, indentation will not be -performed." +performed. + +If the optional argument, INDENT is non-nil, force indentation to +be performed." (interactive) (wesnoth-newline) (when (or wesnoth-auto-indent-flag indent) @@ -634,7 +650,7 @@ the location which an element was expected and the expected element will be displayed in the mini-buffer. START and END define the region to be checked. If -`transient-mark-mode' is enabled, the region specified will be +function `transient-mark-mode' is enabled, the region specified will be checked. Otherwise START and END will be the minimum and maximum positions of the buffer, respectively." (interactive) -- 2.11.4.GIT