Warning, /sdk/kde-dev-scripts/kde-emacs/kde-emacs-doc.el is written in an unsupported language. File is not indexed.
0001 ;; kde-emacs-doc.el
0002 ;;
0003 ;; Copyright (C) 2002 Zack Rusin <zack@kde.org>
0004 ;;
0005 ;; This library is free software; you can redistribute it and/or
0006 ;; modify it under the terms of the GNU Lesser General Public
0007 ;; License as published by the Free Software Foundation; either
0008 ;; version 2.1 of the License, or (at your option) any later version.
0009 ;;
0010 ;; This library is distributed in the hope that it will be useful,
0011 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
0012 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
0013 ;; Lesser General Public License for more details.
0014 ;;
0015 ;; You should have received a copy of the GNU Lesser General Public
0016 ;; License along with this library; if not, write to the Free Software
0017 ;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
0018 ;; 02110-1301 USA
0019 ;;
0020 ;;
0021 ;;; Documentation :
0022 ;; Interactive functions:
0023 ;; kde-license-insert - inserts the chosen license header in the current
0024 ;; buffer,
0025 ;; kde-doc-function-insert - insert documentation skeleton for the function
0026 ;; at the current location
0027 ;; kde-doc-multiline-insert - inserts blank mutliline comment skeleton
0028 ;; kde-doc-oneliner-insert - inserts blank one line comment skeleton
0029 ;;
0030 ;;; TODO :
0031 ;; - add interactive functions to insert file, class, brief,
0032 ;; and group comments,
0033 ;; - change the way commenting works after license insertion,
0034 ;; - add syntax higlighting for doxygen/kdoc keywords
0035 ;; - add more license headers
0036
0037
0038 (require 'kde-emacs-core)
0039 (require 'kde-emacs-semantic)
0040
0041 ;*---------------------------------------------------------------------*/
0042 ;* Licenses ... */
0043 ;*---------------------------------------------------------------------*/
0044
0045 (defvar LGPL "This library is free software; you can redistribute it and/or
0046 modify it under the terms of the GNU Lesser General Public
0047 License as published by the Free Software Foundation; either
0048 version 2.1 of the License, or (at your option) any later version.
0049
0050 This library is distributed in the hope that it will be useful,
0051 but WITHOUT ANY WARRANTY; without even the implied warranty of
0052 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
0053 Lesser General Public License for more details.
0054
0055 You should have received a copy of the GNU General Public License
0056 along with this program. If not, see <http://www.gnu.org/licenses/>."
0057 "GNU LGPL license header.")
0058
0059 (defvar GPL "This program is free software; you can redistribute it and/or
0060 modify it under the terms of the GNU General Public License
0061 as published by the Free Software Foundation; either version 2
0062 of the License, or (at your option) any later version.
0063
0064 This program is distributed in the hope that it will be useful,
0065 but WITHOUT ANY WARRANTY; without even the implied warranty of
0066 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
0067 GNU General Public License for more details.
0068
0069 You should have received a copy of the GNU General Public License
0070 along with this program. If not, see <http://www.gnu.org/licenses/>."
0071 "GNU GPL license header.")
0072
0073 (defvar FDL "Permission is granted to copy, distribute and/or modify this document
0074 under the terms of the GNU Free Documentation License, Version 1.2
0075 or any later version published by the Free Software Foundation;
0076 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
0077 A copy of the license is included in the section entitled \"GNU
0078 Free Documentation License\"."
0079 "GNU FDL license header.")
0080
0081 (defvar BSD "Redistribution and use in source and binary forms, with or without
0082 modification, are permitted provided that the following conditions
0083 are met:
0084
0085 1. Redistributions of source code must retain the above copyright
0086 notice, this list of conditions and the following disclaimer.
0087 2. Redistributions in binary form must reproduce the above copyright
0088 notice, this list of conditions and the following disclaimer in the
0089 documentation and/or other materials provided with the distribution.
0090
0091 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
0092 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
0093 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
0094 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
0095 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
0096 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
0097 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
0098 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0099 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
0100 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
0101 "BSD license header.")
0102
0103
0104 ;;----------------
0105 ;; Variables |
0106 ;;----------------
0107
0108 (defconst kde-doc-styles
0109 '(
0110 (javadoc .
0111 ((start . "/**")
0112 (end . "*/")
0113 (separator . "\n*")
0114 (oneliner . "///")
0115 (element . "/**< */")
0116 (param . "@param %s")
0117 (return . "@return")
0118 (seealso . "@see")
0119 (class . "")
0120 (brief . "@brief")
0121 (file . "@file %s")
0122 ))
0123 (qt .
0124 ((start . "/*!")
0125 (end . "*/")
0126 (separator . "\n")
0127 (oneliner . "//!")
0128 (element . "/*!< */")
0129 (param . "\\param %s")
0130 (return . "\\return")
0131 (seealso . "\\sa")
0132 (class . "\\class")
0133 (brief . "\\brief")
0134 (file . "\\file %s")
0135 ))
0136 )
0137 "Documentation styles used by KDE.")
0138
0139 (defcustom kde-doc-style 'javadoc
0140 "Current documentation style. This variable is buffer local."
0141 :group 'kde-devel
0142 :version "0.1"
0143 :type (if (boundp 'kde-doc-styles)
0144 `(choice ,@(mapcar (lambda (s) `(const ,(car s))) kde-doc-styles))
0145 'symbol))
0146 (make-variable-buffer-local 'kde-doc-style)
0147
0148 (defcustom kde-license-comment-style 'box
0149 "Style to be used for `kde-license-insert'.
0150 See `comment-styles' for a list of available styles."
0151 :group 'kde-devel
0152 :version "0.1"
0153 :type (if (boundp 'comment-styles)
0154 `(choice ,@(mapcar (lambda (s) `(const ,(car s))) comment-styles))
0155 'symbol))
0156
0157 ;*---------------------------------------------------------------------*/
0158 ;* Functions ... */
0159 ;*---------------------------------------------------------------------*/
0160
0161 (defun kde-license-header ()
0162 (let ((ret (file-name-nondirectory (buffer-file-name))))
0163 (setq ret (concat ret " \n\n"))
0164 (setq ret (concat ret "Copyright (C) " (format-time-string "%Y ")
0165 kde-full-name " <"kde-email">\n\n"))
0166 ))
0167
0168 (defun kde-license-insert (license)
0169 "Inserts the chosen license header at the top of the current
0170 buffer."
0171 (interactive (list (completing-read
0172 "Which license do you want to use? "
0173 '(("GNU GPL" 1) ("GNU LGPL" 2) ("GNU FDL" 3) ("BSD" 4))
0174 nil t nil)))
0175 (save-excursion
0176 (let ((start (point-min))
0177 (end)
0178 )
0179 (setq comment-style kde-license-comment-style)
0180 (goto-char start)
0181 (if license
0182 (progn
0183 (cond ((string= license "GNU GPL")
0184 (insert (kde-license-header))
0185 (insert GPL)
0186 )
0187 ((string= license "GNU LGPL")
0188 (insert (kde-license-header))
0189 (insert LGPL)
0190 )
0191 ((string= license "GNU FDL")
0192 (insert (kde-license-header))
0193 (insert FDL)
0194 )
0195 ((string= license "BSD")
0196 (insert (kde-license-header))
0197 (insert BSD)
0198 )
0199 )
0200 (insert "\n")
0201 (setq end (point))
0202 (comment-region start end)
0203 )
0204 )
0205 )
0206 ))
0207
0208 (defmacro kde-doc-type-string (arg)
0209 "Maps doc element from kde-doc-style to string."
0210 `(cdr (assoc ,arg (assoc kde-doc-style kde-doc-styles)))
0211 )
0212
0213 (defun kde-doc-param-string (ARG)
0214 "Substitues %s in the param string with ARG."
0215 (let ((par (kde-doc-type-string 'param)))
0216 (if (string-match "\%s" par)
0217 (replace-match ARG t t par)
0218 par))
0219 )
0220
0221 (defun kde-function-documentation (function)
0222 (let ((ret "") (rettype (semantic-token-type function)))
0223 (setq ret (kde-doc-type-string 'start))
0224 (setq ret (concat ret (kde-doc-type-string 'separator)))
0225 (dolist (elt (semantic-token-function-args function) ret)
0226 (setq ret (concat ret (kde-doc-type-string 'separator) " "
0227 (kde-doc-param-string (semantic-token-name elt))))
0228 )
0229 (if (not (or
0230 (kde-is-constructor function)
0231 (semantic-token-function-destructor function)))
0232 (progn
0233 (if (listp rettype)
0234 (setq rettype (car rettype)))
0235 (if (not (string= rettype "void"))
0236 (setq ret (concat ret (kde-doc-type-string 'separator) " " (kde-doc-type-string 'return)))
0237 )
0238 )
0239 )
0240 (setq ret (concat ret "\n" (kde-doc-type-string 'end) ))
0241 ))
0242
0243 (defun kde-doc-function-insert ()
0244 "Inserts skeleton function documentation for a function
0245 at the current location."
0246 (interactive)
0247 (save-excursion
0248 (let* ((pt (point))
0249 (token (kde-function-at-point pt))
0250 (ret "")
0251 (start) (end)
0252 )
0253 (if (not token)
0254 (error "There's no function at %d." pt)
0255 (progn
0256 (setq ret (kde-function-documentation token))
0257 (goto-char (semantic-token-start token))
0258 (previous-line)
0259 (goto-char (point-at-eol))
0260 (setq start (point))
0261 (insert "\n " ret)
0262 (setq end (semantic-token-end token))
0263 (indent-region start end nil)
0264 )
0265 )
0266 )))
0267
0268 (defun kde-doc-oneliner-insert ()
0269 "Insert oneliner comment at the current point. If the line is not empty newline is inserted."
0270 (interactive)
0271 (let ((thisblank)(pt))
0272 (save-excursion
0273 (beginning-of-line)
0274 (setq pt (point))
0275 (setq thisblank (looking-at "[ \t]*$"))
0276 (if (not thisblank)
0277 (progn
0278 (newline)
0279 (goto-char pt)
0280 ))
0281 (insert (kde-doc-type-string 'oneliner))
0282 (setq pt (point-at-eol))
0283 (end-of-line)
0284 )
0285 (goto-char pt)
0286 ))
0287
0288 (defun kde-doc-multiline-insert ()
0289 "Inserts blank multiline comment at point. If the current line isn't blank
0290 the functions inserts a newline."
0291 (interactive)
0292 (let ((thisblank)(start) (end))
0293 (save-excursion
0294 (beginning-of-line)
0295 (setq start (point))
0296 (setq thisblank (looking-at "[ \t]*$"))
0297 (if (not thisblank)
0298 (progn
0299 (newline)
0300 (goto-char start)
0301 ))
0302 ;; The blank to fix sometimes occuring
0303 ;; weird behavior in indent-region
0304 (insert " "
0305 (kde-doc-type-string 'start)
0306 (kde-doc-type-string 'separator) "\n"
0307 (kde-doc-type-string 'end)
0308 )
0309 (setq end (point))
0310 (indent-region start end nil)
0311 )
0312 (goto-char start)
0313 (end-of-line)
0314 ))
0315
0316
0317 (provide 'kde-emacs-doc)