cgit.sxemacs.org Git - packages/blob - xemacs-packages/semantic/document-vars.el

   1 ;;; document-vars.el --- Default settings for the document package.
   2
   3 ;;; Copyright (C) 2000, 2001 Eric M. Ludlam
   4
   5 ;; Author: Eric M. Ludlam <zappo@gnu.org>
   6 ;; Keywords: doc
   7 ;; X-RCS: $Id: document-vars.el,v 1.4 2005/09/30 20:18:39 zappo Exp $
   8
   9 ;; This file is not part of GNU Emacs.
  10
  11 ;; Semantic is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; This software is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  24 ;; Boston, MA 02110-1301, USA.
  25
  26 ;;; Commentary:
  27 ;;
  28 ;; Default settings for the document comment generation package.
  29
  30
  31 ;;; Code:
  32 (provide 'document-vars)
  33
  34 (eval-when-compile
  35   ;; Emacs 21
  36   (condition-case nil
  37       (require 'newcomment)
  38     (error nil))
  39   )
  40
  41 (defvar document-comment-start nil
  42   "Comment start string.")
  43
  44 (defvar document-comment-line-prefix nil
  45   "Comment prefix string.  Used at the beginning of each line.")
  46
  47 (defvar document-comment-end nil
  48   "Comment end string.")
  49
  50 (defcustom document-copyright-notice-file nil
  51   "*A file name containing a copyright notice.
  52 It will be reformatted in the header to have the correct prefix character.
  53 See the %N token in `document-file-comment'"
  54   :group 'document
  55   :type 'file)
  56
  57 (defcustom document-change-number nil
  58   "*The current change number being worked on.
  59 Large projects may use change numbers, bug numbers, or other tag."
  60   :group 'document
  61   :type 'string)
  62
  63 (defcustom document-extra-line-after-short-parameters t
  64   "*Non-nil to add an extra line when there is < 1 arguments."
  65   :group 'document
  66   :type 'string)
  67
  68 (defvar document-comment-left-edge-character nil
  69   "*Language/preference specific characters to use in comments.")
  70
  71 (defcustom document-file-comment "%s %B
  72 %m
  73 %m Copyright (C) %Y %O
  74 %m
  75 %m %N
  76 %m
  77 %m Description:
  78 %m
  79 %m   %D
  80 %m
  81 %m History:
  82 %m %H
  83 %m
  84 %m Tokens: %T
  85 %e
  86 "
  87   "Comment block for the beginning of a new file.
  88 The format tokens available are:
  89  %B - Brief description of the file (Auto-comment by file name)
  90  %D - Made up documentation
  91  %N - Copyright notice for your organization
  92  %O - Owner (full name of copyright holder held in `document-copyright-holder'
  93  %H - History elements
  94  %T - cproto header id token.  Always is form 'token file.h' where
  95       token is defined in cpr-header-token, and file.h is the
  96       relational file name of the header.  If you wish to use cproto's
  97       features, you must have this somewhere in the header.
  98  %Y - Year
  99 Commenting elements:
 100  %b - Comment start string
 101  %m - Comment line prefix (not the start)
 102  %e - Comment end string"
 103   :group 'document
 104   :type 'string)
 105
 106 (defcustom document-header-comment "%b
 107 %m Copyright (c) %Y %O
 108 %m
 109 %m %N
 110 %m
 111 %m History:
 112 %m %H
 113 %e
 114 "
 115   "Comment block for the beginning of a new header/dependency file.
 116 The format tokens available are the same as for `document-file-comment'"
 117   :group 'document
 118   :type 'string)
 119
 120 (defcustom document-file-brief-comment "%F - %C"
 121   "Format of the brief comment with tokens.
 122 Available tokens are:
 123  %F - file name short
 124  %C - Comment field"
 125   :group 'document
 126   :type 'string)
 127
 128 (defcustom document-function-comment "\f
 129 %b
 130 %m Function: %F
 131 %m
 132 %m %f  %D%p
 133 %m
 134 %m Returns:     %R
 135 %m Parameters:  %P
 136 %m History:
 137 %m %H
 138 %e
 139 "
 140   "Comment block for the beginning of a new function/variable definition.
 141 There are several format tokens represent the following:
 142   %F - function name
 143   %D - Made up documentation
 144   %f - Place, where everything before the point is the distance to set
 145        in the fill prefix.  Allows a first line in paragraph indent
 146   %p - Where to place point after insertion of a new header
 147   %R - Returns
 148   %P - Parameter list
 149   %H - History insertion point
 150
 151   The parts %f and %p can be confusing, so here is an example:
 152
 153  * Moose: %f%D%p
 154
 155  Will set fill prefix to ` *         `, and put the point AFTER the
 156 description.  The `Moose:` will not be in the prefix.  The default
 157 value shows the equivalent of a hanging indent.
 158
 159 Commenting elements:
 160  %b - Comment start string
 161  %m - Comment line prefix (not the start)
 162  %e - Comment end string"
 163   :group 'document
 164   :type 'string)
 165
 166 (defcustom document-param-element "%P - %D"
 167   "The format of a parameter element in the list of parameters.
 168 The parts are:
 169  %P - Parameter name spaced to length of max param
 170  %p - Parameter name with no padding
 171  %R - Type of element
 172  %D - Description of parameter as known by document."
 173   :group 'document
 174   :type 'string)
 175
 176 (defcustom document-history-element "%-7U %-10D %C"
 177   "Format for history element.
 178 Valid % codes are:
 179   %U - Username, initials, what have you.
 180   %D - The current date formatted as in `document-date-element'
 181   %S - System Change id, SCCS vers, major change comment, etc
 182   %C - Auto comment area, cursor goes here for new elts."
 183   :group 'document
 184   :type 'string)
 185
 186 (defcustom document-date-element "%M/%D/%y"
 187   "Format for date elements.
 188 Valid format chars are:
 189   %H - Hours
 190   %h - Hours 24 hr format
 191   %a - AM/PM flag
 192   %I - mInutes
 193   %S - Seconds
 194   %D - Day
 195   %w - Weekday string
 196   %M - Month as number
 197   %m - Month as string
 198   %Y - Year
 199   %y - Year as 2 numbers 1994 -> 94"
 200   :group 'document
 201   :type 'string)
 202
 203 (defcustom document-autocomment-function-alist
 204   '(
 205     ("abort" . "Aborts the")
 206     ;; trick to get re-alloc and alloc to pair into one sentence.
 207     ("realloc" . "moves or ")
 208     ("alloc\\(ate\\)?" . "Allocates and initializes a new ")
 209     ("clean" . "Cleans up the")
 210     ("clobber" . "Removes")
 211     ("close" . "Cleanly closes")
 212     ("check" . "Checks the")
 213     ("comp\\(are\\)?" . "Compares the")
 214     ("create" . "Creates a new ")
 215     ("find" . "Finds ")
 216     ("free" . "Frees up space")
 217     ("gen\\(erate\\)?" . "Generates a new ")
 218     ("get\\|find" . "Looks for the given ")
 219     ("gobble" . "Removes")
 220     ("he?lp" . "Provides help for")
 221     ("li?ste?n" . "Listens for ")
 222     ("connect" . "Connects to ")
 223     ("acc?e?pt" . "Accepts a ")
 224     ("load" . "Loads in ")
 225     ("match" . "Check that parameters match")
 226     ("name" . "Provides a name which ")
 227     ("parse" . "Parses the parameters and returns ")
 228     ("print\\|display" . "Prints out")
 229     ("read" . "Reads from")
 230     ("reset" . "Resets the parameters and returns")
 231     ("scan" . "Scans the ")
 232     ("setup\\|init\\(iallize\\)?" . "Initializes the ")
 233     ("select" . "Chooses the ")
 234     ("send" . "Sends a")
 235     ("re?c\\(v\\|ieves?\\)" . "Receives a ")
 236     ("wait" . "Waits for ")
 237     ("write" . "Writes to")
 238     )
 239   "List of names to string match against the function name.
 240 This is an alist with each element of the form:
 241  (MATCH . RESULT)
 242 MATCH is a regexp to match in the type field.
 243 RESULT is a string.
 244
 245 Certain prefixes may always mean the same thing, and the same comment
 246 can be used as a beginning for the description.  Regexp should be
 247 lower case since the string they are compared to is downcased.
 248 A string may end in a space, in which case, last-alist is searched to
 249 see how best to describe what can be returned.
 250 Doesn't always work correctly, but that is just because English
 251 doesn't always work correctly."
 252   :group 'document
 253   :type '(repeat (cons (string :tag "Regexp")
 254                        (string :tag "Doc Text"))))
 255
 256 (defcustom document-autocomment-common-nouns-abbrevs
 257   '(
 258     ("sock\\(et\\)?" . "socket")
 259     ("addr\\(ess\\)?" . "address")
 260     ("buf\\(f\\(er\\)?\\)?" . "buffer")
 261     ("cur\\(r\\(ent\\)?\\)?" . "current")
 262     ("dev\\(ice\\)?" . "device")
 263     ("file" . "file")
 264     ("line" . "line")
 265     ("msg\\|message" . "message")
 266     ("name" . "name")
 267     ("next\\|nxt" . "next")
 268     ("port" . "port")
 269     ("host" . "host")
 270     ("obj\\|object" . "object")
 271     ("previous\\|prev" . "previous")
 272     ("str\\(ing\\)?" . "string")
 273     ("use?r" . "user")
 274     ("num\\(ber\\)?" . "number")
 275     ("\\(^\\|\\s-\\)id\\($\\|\\s-\\)" . "Identifier") ;complex cause ;commen sylable
 276     )
 277   "List of common English abbreviations or full words.
 278 These are nouns (as opposed to verbs) for use in creating expanded
 279 versions of names.This is an alist with each element of the form:
 280  (MATCH . RESULT)
 281 MATCH is a regexp to match in the type field.
 282 RESULT is a string."
 283   :group 'document
 284   :type '(repeat (cons (string :tag "Regexp")
 285                        (string :tag "Doc Text"))))
 286
 287 (defcustom document-autocomment-return-first-alist
 288   '(
 289     ;; Static must be first in the list to provide the intro to the sentence
 290     ("static" . "Locally defined function which ")
 291     ("Bool\\|BOOL" . "Status of ")
 292     )
 293   "List of regexp matches for types.
 294 They provide a little bit of text when typing information is
 295 described.
 296 This is an alist with each element of the form:
 297  (MATCH . RESULT)
 298 MATCH is a regexp to match in the type field.
 299 RESULT is a string."
 300   :group 'document
 301   :type '(repeat (cons (string :tag "Regexp")
 302                        (string :tag "Doc Text"))))
 303
 304 (defcustom document-autocomment-return-last-alist
 305   '(
 306     ("static[ \t\n]+struct \\([a-zA-Z0-9_]+\\)" . "%s")
 307     ("struct \\([a-zA-Z0-9_]+\\)" . "%s")
 308     ("static[ \t\n]+union \\([a-zA-Z0-9_]+\\)" . "%s")
 309     ("union \\([a-zA-Z0-9_]+\\)" . "%s")
 310     ("static[ \t\n]+enum \\([a-zA-Z0-9_]+\\)" . "%s")
 311     ("enum \\([a-zA-Z0-9_]+\\)" . "%s")
 312     ("static[ \t\n]+\\([a-zA-Z0-9_]+\\)" . "%s")
 313     ("\\([a-zA-Z0-9_]+\\)" . "of type %s")
 314     )
 315   "List of regexps which provide the type of the return value.
 316 This is an alist with each element of the form:
 317  (MATCH . RESULT)
 318 MATCH is a regexp to match in the type field.
 319 RESULT is a string, which can contain %s, whih is replaced with
 320 `match-string' 1."
 321   :group 'document
 322   :type '(repeat (cons (string :tag "Regexp")
 323                        (string :tag "Doc Text"))))
 324
 325 (defcustom document-autocomment-param-alist
 326   '( ("[Cc]txt" . "Context")
 327      ("[Ii]d" . "Identifier of")
 328      ("[Tt]ype" . "Type of")
 329      ("[Nn]ame" . "Name of")
 330      ("argc" . "Number of arguments")
 331      ("argv" . "Argument vector")
 332      ("envp" . "Environment variable vector")
 333      )
 334   "Alist of common variable names appearing as function parameters.
 335 This is an alist with each element of the form:
 336  (MATCH . RESULT)
 337 MATCH is a regexp to match in the type field.
 338 RESULT is a string of text to use to describe MATCH.
 339 When one is encountered, document-insert-parameters will automatically
 340 place this comment after the parameter name."
 341   :group 'document
 342   :type '(repeat (cons (string :tag "Regexp")
 343                        (string :tag "Doc Text"))))
 344
 345 (defcustom document-autocomment-param-type-alist
 346   '(("const" . "Constant")
 347     ("void" . "Empty")
 348     ("char[ ]*\\*" . "String ")
 349     ("\\*\\*" . "Pointer to ")
 350     ("\\*" . "Pointer ")
 351     ("char[ ]*\\([^ \t*]\\|$\\)" . "Character")
 352     ("int\\|long" . "Number of")
 353     ("FILE" . "File of")
 354     ("float\\|double" . "Value of")
 355     ;; How about some X things?
 356     ("Bool\\|BOOL" . "Flag")
 357     ("Window" . "Window")
 358     ("GC" . "Graphic Context")
 359     ("Widget" . "Widget")
 360     )
 361   "Alist of input parameter types and strings desribing them.
 362 This is an alist with each element of the form:
 363  (MATCH . RESULT)
 364 MATCH is a regexp to match in the type field.
 365 RESULT is a string."
 366   :group 'document
 367   :type '(repeat (cons (string :tag "Regexp")
 368                        (string :tag "Doc Text"))))
 369
 370 (defcustom document-new-hist-comment "Created"
 371   "Comment used in the history when something is created."
 372   :group 'document
 373   :type 'string)
 374
 375 (defvar document-autocomment-modify-alist
 376   '((document-newparam . "%s")
 377     )
 378   "Alist of history change calculations.
 379 This is an alist with each element of the form:
 380  (FUNCTION . RESULT)
 381 FUNCTION is a function to run to check for chnges.
 382 RESULT is a string with %s being filled with change text.")
 383
 384 ;;; A few fns to access some variables.
 385 (defun document-comment-start ()
 386   "Derive a string to start a comment in this mode."
 387   (or document-comment-start
 388       block-comment-start
 389       comment-start))
 390
 391 (defun document-comment-line-prefix ()
 392   "Derive a string to end a comment in this mode."
 393   (or document-comment-line-prefix
 394       ""))
 395
 396 (defun document-comment-end ()
 397   "Derive a string to end a comment in this mode."
 398   (or document-comment-end
 399       block-comment-end
 400       "\n"))
 401
 402 ;;; document-vars.el ends here