tools/gtk-doc.el

   1
   2 ;; Copyright (C) 1998 Michael Zucchi
   3
   4 ;; This program is free software; you can redistribute it and/or
   5 ;; modify it under the terms of the GNU General Public License as
   6 ;; published by the Free Software Foundation; either version 2 of
   7 ;; the License, or (at your option) any later version.
   8
   9 ;; This program is distributed in the hope that it will be
  10 ;; useful, but WITHOUT ANY WARRANTY; without even the implied
  11 ;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  12 ;; PURPOSE.  See the GNU General Public License for more details.
  13
  14 ;; You should have received a copy of the GNU General Public
  15 ;; License along with this program; if not, write to the Free
  16 ;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  17 ;; MA 0211
  18 ;;
  19
  20 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  21
  22 ;;  This file auto-generates a C function document header from the
  23 ;;  current function.
  24
  25 ;;  Load into emacs (e.g. add (load "~/gtk-doc.el") to your .emacs file)
  26 ;;  and use C-x4h, or M-x gtk-doc-insert to insert a new header for
  27 ;;  the current function.  You have to be somewhere in the body of the
  28 ;;  function you wish to document.
  29
  30 ;;  You can also now use C-x4s to insert a blank section header.
  31
  32 ;;  The default header format is setup to do 'gnome' style headers.
  33 ;;  These headers are used in the Gnome project to automatically
  34 ;;  produce SGML API documentation directly from the source code.
  35
  36 ;;  These headers look something like this (the cursor is left at
  37 ;;  the '_'):
  38
  39 ;;  /**
  40 ;;   * function_name:
  41 ;;   * @param1:
  42 ;;   * @param2:
  43 ;;   *
  44 ;;   * _
  45 ;;   *
  46 ;;   * Returns:
  47 ;;   **/
  48 ;;  int function_name(char *param1, int param2)
  49 ;;  {
  50 ;;  ...
  51
  52 ;;  It should be able to transform this into quite a few different
  53 ;;  header formats by customising the options.
  54
  55 ;;  For example, for a more gnu-ish header style, the following
  56 ;;  settings could be used:
  57
  58 ;;  (setq-default gnome-doc-header "/* %s\n")
  59 ;; or for no function name in the header:
  60 ;;      (setq-default gnome-doc-header "/* \n")
  61
  62 ;;  (setq-default gnome-doc-blank "   \n")
  63 ;; or for more compact version:
  64 ;;      (setq-default gnome-doc-blank "")
  65
  66 ;;  (setq-default gnome-doc-parameter "   %s: \n")
  67 ;; or to exclude parameters:
  68 ;;       (setq-default gnome-doc-parameter "")
  69
  70 ;;  (setq-default gnome-doc-trailer "   */\n")
  71 ;;  (setq-default gnome-doc-section "   %s: \n")
  72 ;;  (setq-default gnome-doc-match-block "^  ")
  73 ;;  (setq-default gnome-doc-match-header "^/\\*")
  74
  75 ;; The important thing is to ensure all lines match
  76 ;; the gnome-doc-match-block regular expression.
  77
  78 ;; This will produce something like this:
  79
  80 ;; /* function_name
  81 ;;    param1:
  82 ;;    param2:
  83 ;;
  84 ;;    _
  85 ;;
  86 ;;    Returns:
  87 ;;    */
  88
  89 ;; With the blank line defined as "", a much more
  90 ;; compact version is generated:
  91
  92 ;; /* function_name
  93 ;;    param1:
  94 ;;    param2: _
  95 ;;    Returns:
  96 ;;    */
  97
  98 ;;;;
  99 ;; This is my first attempt at anything remotely lisp-like, you'll just
 100 ;; have to live with it :)
 101 ;;
 102 ;; It works ok with emacs-20, AFAIK it should work on other versions too.
 103
 104 (defgroup gnome-doc nil
 105   "Generates automatic headers for functions"
 106   :prefix "gnome"
 107   :group 'tools)
 108
 109 (defcustom gnome-doc-header "/**\n * %s:\n"
 110   "Start of documentation header.
 111
 112 Using '%s' will expand to the name of the function."
 113   :type '(string)
 114   :group 'gnome-doc)
 115
 116 (defcustom gnome-doc-blank " *\n"
 117   "Used to put a blank line into the header."
 118   :type '(string)
 119   :group 'gnome-doc)
 120
 121 (defcustom gnome-doc-blank-space " * \n"
 122   "Used to put a blank line into the header, plus a space"
 123   :type '(string)
 124   :group 'gnome-doc)
 125
 126 (defcustom gnome-doc-trailer " **/\n"
 127   "End of documentation header.
 128
 129 Using '%s' will expand to the name of the function being defined."
 130   :type '(string)
 131   :group 'gnome-doc)
 132
 133 (defcustom gnome-doc-parameter " * @%s: \n"
 134   "Used to add another parameter to the header.
 135
 136 Using '%s' will be replaced with the name of the parameter."
 137   :type '(string)
 138   :group 'gnome-doc)
 139
 140 (defcustom gnome-doc-section " * %s: \n"
 141   "How to define a new section in the output.
 142
 143 Using '%s' is replaced with the name of the section.
 144 Currently this will only be used to define the 'returns' field."
 145   :type '(string)
 146   :group 'gnome-doc)
 147
 148 (defcustom gnome-doc-match-block "^ \\*"
 149   "Regular expression which matches all lines in the header.
 150
 151 It should match every line produced by any of the header specifiers.
 152 It is therefore convenient to start all header lines with a common
 153 comment prefix"
 154   :type '(string)
 155   :group 'gnome-doc)
 156
 157 (defcustom gnome-doc-match-header "^/\\*\\*"
 158   "Regular expression which matches the first line of the header.
 159
 160 It is used to identify if a header has already been applied to this
 161 function.  It should match the line produced by gnome-doc-header, or
 162 at least the first line of this which matches gnome-doc-match-block"
 163   :type '(string)
 164   :group 'gnome-doc)
 165
 166
 167 (make-variable-buffer-local 'gnome-doc-header)
 168 (make-variable-buffer-local 'gnome-doc-trailer)
 169 (make-variable-buffer-local 'gnome-doc-parameter)
 170 (make-variable-buffer-local 'gnome-doc-section)
 171 (make-variable-buffer-local 'gnome-doc-blank)
 172 (make-variable-buffer-local 'gnome-doc-blank-space)
 173 (make-variable-buffer-local 'gnome-doc-match-block)
 174 (make-variable-buffer-local 'gnome-doc-match-header)
 175
 176 ;; insert header at current location
 177 (defun gnome-doc-insert-header (function)
 178   (insert (format gnome-doc-header function)))
 179
 180 ;; insert a single variable, at current location
 181 (defun gnome-doc-insert-var (var)
 182   (insert (format gnome-doc-parameter var)))
 183
 184 ;; insert a 'blank' comment line
 185 (defun gnome-doc-insert-blank ()
 186   (insert gnome-doc-blank))
 187
 188 ;; insert a 'blank-space' comment line
 189 (defun gnome-doc-insert-blank-space ()
 190   (insert gnome-doc-blank-space))
 191
 192 ;; insert a section comment line
 193 (defun gnome-doc-insert-section (section)
 194   (insert (format gnome-doc-section section)))
 195
 196 ;; insert the end of the header
 197 (defun gnome-doc-insert-footer (func)
 198   (insert (format gnome-doc-trailer func)))
 199
 200 (defun gtk-doc-insert ()
 201   "Add a documentation header to the current function.
 202 Only C/C++ function types are properly supported currently."
 203   (interactive)
 204   (let (c-insert-here (point))
 205     (save-restriction
 206       (save-excursion
 207         (beginning-of-defun)
 208         (narrow-to-page)
 209         (let (c-arglist
 210               c-funcname
 211               c-point
 212               c-comment-point
 213               c-isvoid
 214               c-doinsert)
 215           (while (or (looking-at "^$")
 216                      (looking-at "^ *}")
 217                      (looking-at "^ \\*")
 218                      (looking-at "^#"))
 219             (forward-line 1))
 220           (if (or (looking-at ".*void.*(")
 221                   (looking-at ".*void[ \t]*$"))
 222               (setq c-isvoid 1))
 223
 224           (setq c-point point)
 225
 226           (save-excursion
 227             (if (re-search-forward "\\([A-Za-z0-9_:~]+\\)[ \t\n]*\\(([^)]*)\\)" c-point nil)
 228                 (let ((c-argstart (match-beginning 2))
 229                       (c-argend (match-end 2)))
 230                   (setq c-funcname (buffer-substring (match-beginning 1) (match-end 1)))
 231                   (goto-char c-argstart)
 232                   (while (re-search-forward "\\([A-Za-z0-9_]*\\) *[,)]" c-argend t)
 233                     (setq c-arglist
 234                           (append c-arglist
 235                                   (list (buffer-substring (match-beginning 1) (match-end 1)))))))))
 236
 237           ;; see if we already have a header here ...
 238           (save-excursion
 239             (forward-line -1)
 240             (while (looking-at gnome-doc-match-block)
 241               (forward-line -1))
 242             (if (looking-at gnome-doc-match-header)
 243                 (error "Header already exists")
 244               (setq c-doinsert t)))
 245
 246           ;; insert header
 247           (if c-doinsert
 248               (progn
 249                 (gnome-doc-insert-header c-funcname)
 250
 251                 ;; all arguments
 252                 (while c-arglist
 253                   (gnome-doc-insert-var (car c-arglist))
 254                   (setq c-arglist (cdr c-arglist)))
 255
 256                 ;; finish it off
 257                 (gnome-doc-insert-blank)
 258                 (gnome-doc-insert-blank-space)
 259                 ;; record the point of insertion
 260                 (setq c-insert-here (- (point) 1))
 261
 262                 ;; only insert a returns if we have one ...
 263                 (if (not c-isvoid)
 264                     (progn
 265                       (gnome-doc-insert-blank)
 266                       (gnome-doc-insert-section "Returns")))
 267
 268                 (gnome-doc-insert-footer c-funcname))))))
 269
 270     ;; goto the start of the description saved above
 271     (goto-char c-insert-here)))
 272
 273
 274 ;; set global binding for this key (follows the format for
 275 ;;   creating a changelog entry ...)
 276 (global-set-key "\C-x4h"  'gtk-doc-insert)
 277
 278
 279 ;; Define another function for inserting a section header.
 280 (defun gtk-doc-insert-section ()
 281   "Add a section documentation header at the current position."
 282   (interactive)
 283   (insert "/**\n"
 284           " * SECTION:\n"
 285           " * @Title: \n"
 286           " * @Short_Description: \n"
 287           " * @Stability_Level: \n"
 288           " * @See_Also: \n"
 289           " *\n"
 290           " * \n"
 291           " */\n"))
 292
 293 ;; Set the key binding.
 294 (global-set-key "\C-x4s" 'gtk-doc-insert-section)