summaryrefslogtreecommitdiffstats
path: root/scripts/kde-emacs/kde-emacs-doc.el
diff options
context:
space:
mode:
Diffstat (limited to 'scripts/kde-emacs/kde-emacs-doc.el')
-rw-r--r--scripts/kde-emacs/kde-emacs-doc.el322
1 files changed, 322 insertions, 0 deletions
diff --git a/scripts/kde-emacs/kde-emacs-doc.el b/scripts/kde-emacs/kde-emacs-doc.el
new file mode 100644
index 00000000..5fca1361
--- /dev/null
+++ b/scripts/kde-emacs/kde-emacs-doc.el
@@ -0,0 +1,322 @@
+;; kde-emacs-doc.el
+;;
+;; Copyright (C) 2002 Zack Rusin <zack@kde.org>
+;;
+;; This library is free software; you can redistribute it and/or
+;; modify it under the terms of the GNU Lesser General Public
+;; License as published by the Free Software Foundation; either
+;; version 2.1 of the License, or (at your option) any later version.
+;;
+;; This library is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+;; Lesser General Public License for more details.
+;;
+;; You should have received a copy of the GNU Lesser General Public
+;; License along with this library; if not, write to the Free Software
+;; Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA
+;; 02110-1301 USA
+;;
+;;
+;;; Documentation :
+;; Interactive functions:
+;; kde-license-insert - inserts the chosen license header in the current
+;; buffer,
+;; kde-doc-function-insert - insert documentation skeleton for the function
+;; at the current location
+;; kde-doc-multiline-insert - inserts blank mutliline comment skeleton
+;; kde-doc-oneliner-insert - inserts blank one line comment skeleton
+;;
+;;; TODO :
+;; - add interactive functions to insert file, class, brief,
+;; and group comments,
+;; - change the way commenting works after license insertion,
+;; - add syntax higlighting for doxygen/kdoc keywords
+;; - add more license headers
+
+
+(require 'kde-emacs-core)
+(require 'kde-emacs-semantic)
+
+;*---------------------------------------------------------------------*/
+;* Licenses ... */
+;*---------------------------------------------------------------------*/
+
+(defvar LGPL "This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA
+02110-1301 USA"
+ "GNU LGPL license header.")
+
+(defvar GPL "This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA
+02110-1301, USA."
+ "GNU GPL license header.")
+
+(defvar FDL "Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the Invariant Sections being LIST THEIR TITLES, with the
+Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+A copy of the license is included in the section entitled \"GNU
+Free Documentation License\"."
+ "GNU FDL license header.")
+
+(defvar BSD "Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+ "BSD license header.")
+
+
+;;----------------
+;; Variables |
+;;----------------
+
+(defconst kde-doc-styles
+ '(
+ (javadoc .
+ ((start . "/**")
+ (end . "*/")
+ (separator . "\n*")
+ (oneliner . "///")
+ (element . "/**< */")
+ (param . "@param %s")
+ (return . "@return")
+ (seealso . "@see")
+ (class . "")
+ (brief . "@brief")
+ (file . "@file %s")
+ ))
+ (qt .
+ ((start . "/*!")
+ (end . "*/")
+ (separator . "\n")
+ (oneliner . "//!")
+ (element . "/*!< */")
+ (param . "\\param %s")
+ (return . "\\return")
+ (seealso . "\\sa")
+ (class . "\\class")
+ (brief . "\\brief")
+ (file . "\\file %s")
+ ))
+ )
+ "Documentation styles used by KDE.")
+
+(defcustom kde-doc-style 'javadoc
+ "Current documentation style. This variable is buffer local."
+ :group 'kde-devel
+ :version "0.1"
+ :type (if (boundp 'kde-doc-styles)
+ `(choice ,@(mapcar (lambda (s) `(const ,(car s))) kde-doc-styles))
+ 'symbol))
+(make-variable-buffer-local 'kde-doc-style)
+
+(defcustom kde-license-comment-style 'box
+ "Style to be used for `kde-license-insert'.
+See `comment-styles' for a list of available styles."
+ :group 'kde-devel
+ :version "0.1"
+ :type (if (boundp 'comment-styles)
+ `(choice ,@(mapcar (lambda (s) `(const ,(car s))) comment-styles))
+ 'symbol))
+
+;*---------------------------------------------------------------------*/
+;* Functions ... */
+;*---------------------------------------------------------------------*/
+
+(defun kde-license-header ()
+ (let ((ret (file-name-nondirectory (buffer-file-name))))
+ (setq ret (concat ret " \n\n"))
+ (setq ret (concat ret "Copyright (C) " (format-time-string "%Y ")
+ kde-full-name " <"kde-email">\n\n"))
+ ))
+
+(defun kde-license-insert (license)
+ "Inserts the chosen license header at the top of the current
+buffer."
+ (interactive (list (completing-read
+ "Which license do you want to use? "
+ '(("GNU GPL" 1) ("GNU LGPL" 2) ("GNU FDL" 3) ("BSD" 4))
+ nil t nil)))
+ (save-excursion
+ (let ((start (point-min))
+ (end)
+ )
+ (setq comment-style kde-license-comment-style)
+ (goto-char start)
+ (if license
+ (progn
+ (cond ((string= license "GNU GPL")
+ (insert (kde-license-header))
+ (insert GPL)
+ )
+ ((string= license "GNU LGPL")
+ (insert (kde-license-header))
+ (insert LGPL)
+ )
+ ((string= license "GNU FDL")
+ (insert (kde-license-header))
+ (insert FDL)
+ )
+ ((string= license "BSD")
+ (insert (kde-license-header))
+ (insert BSD)
+ )
+ )
+ (insert "\n")
+ (setq end (point))
+ (comment-region start end)
+ )
+ )
+ )
+ ))
+
+(defmacro kde-doc-type-string (arg)
+ "Maps doc element from kde-doc-style to string."
+ `(cdr (assoc ,arg (assoc kde-doc-style kde-doc-styles)))
+ )
+
+(defun kde-doc-param-string (ARG)
+ "Substitues %s in the param string with ARG."
+ (let ((par (kde-doc-type-string 'param)))
+ (if (string-match "\%s" par)
+ (replace-match ARG t t par)
+ par))
+ )
+
+(defun kde-function-documentation (function)
+ (let ((ret "") (rettype (semantic-token-type function)))
+ (setq ret (kde-doc-type-string 'start))
+ (setq ret (concat ret (kde-doc-type-string 'separator)))
+ (dolist (elt (semantic-token-function-args function) ret)
+ (setq ret (concat ret (kde-doc-type-string 'separator) " "
+ (kde-doc-param-string (semantic-token-name elt))))
+ )
+ (if (not (or
+ (kde-is-constructor function)
+ (semantic-token-function-destructor function)))
+ (progn
+ (if (listp rettype)
+ (setq rettype (car rettype)))
+ (if (not (string= rettype "void"))
+ (setq ret (concat ret (kde-doc-type-string 'separator) " " (kde-doc-type-string 'return)))
+ )
+ )
+ )
+ (setq ret (concat ret "\n" (kde-doc-type-string 'end) ))
+ ))
+
+(defun kde-doc-function-insert ()
+ "Inserts skeleton function documentation for a function
+at the current location."
+ (interactive)
+ (save-excursion
+ (let* ((pt (point))
+ (token (kde-function-at-point pt))
+ (ret "")
+ (start) (end)
+ )
+ (if (not token)
+ (error "There's no function at %d." pt)
+ (progn
+ (setq ret (kde-function-documentation token))
+ (goto-char (semantic-token-start token))
+ (previous-line)
+ (goto-char (point-at-eol))
+ (setq start (point))
+ (insert "\n " ret)
+ (setq end (semantic-token-end token))
+ (indent-region start end nil)
+ )
+ )
+ )))
+
+(defun kde-doc-oneliner-insert ()
+ "Insert oneliner comment at the current point. If the line is not empty newline is inserted."
+ (interactive)
+ (let ((thisblank)(pt))
+ (save-excursion
+ (beginning-of-line)
+ (setq pt (point))
+ (setq thisblank (looking-at "[ \t]*$"))
+ (if (not thisblank)
+ (progn
+ (newline)
+ (goto-char pt)
+ ))
+ (insert (kde-doc-type-string 'oneliner))
+ (setq pt (point-at-eol))
+ (end-of-line)
+ )
+ (goto-char pt)
+ ))
+
+(defun kde-doc-multiline-insert ()
+ "Inserts blank multiline comment at point. If the current line isn't blank
+the functions inserts a newline."
+ (interactive)
+ (let ((thisblank)(start) (end))
+ (save-excursion
+ (beginning-of-line)
+ (setq start (point))
+ (setq thisblank (looking-at "[ \t]*$"))
+ (if (not thisblank)
+ (progn
+ (newline)
+ (goto-char start)
+ ))
+ ;; The blank to fix sometimes occuring
+ ;; weird behavior in indent-region
+ (insert " "
+ (kde-doc-type-string 'start)
+ (kde-doc-type-string 'separator) "\n"
+ (kde-doc-type-string 'end)
+ )
+ (setq end (point))
+ (indent-region start end nil)
+ )
+ (goto-char start)
+ (end-of-line)
+ ))
+
+
+(provide 'kde-emacs-doc)