Mercurial > emacs
diff lispref/tips.texi @ 26696:ef5e7bbe6f19
Current version from /gd/gnu/elisp.
author | Dave Love <fx@gnu.org> |
---|---|
date | Fri, 03 Dec 1999 19:11:12 +0000 |
parents | df0efa93750b |
children | f6b52258db6a |
line wrap: on
line diff
--- a/lispref/tips.texi Fri Dec 03 19:08:52 1999 +0000 +++ b/lispref/tips.texi Fri Dec 03 19:11:12 1999 +0000 @@ -423,19 +423,19 @@ An internal variable or subroutine of a Lisp program might as well have a documentation string. In earlier Emacs versions, you could save space by using a comment instead of a documentation string, but that is no -longer the case. +longer the case---documentation strings now take up very little space in +a running Emacs. @item The first line of the documentation string should consist of one or two complete sentences that stand on their own as a summary. @kbd{M-x -apropos} displays just the first line, and if it doesn't stand on its -own, the result looks bad. In particular, start the first line with a -capital letter and end with a period. +apropos} displays just the first line, and if that line's contents don't +stand on their own, the result looks bad. In particular, start the +first line with a capital letter and end with a period. -The documentation string can have additional lines that expand on the -details of how to use the function or variable. The additional lines -should be made up of complete sentences also, but they may be filled if -that looks good. +The documentation string is not limited to one line; use as many lines +as you need to explain the details of how to use the function or +variable. Please use complete sentences in the additional lines. @item For consistency, phrase the verb in the first sentence of a function's @@ -457,17 +457,27 @@ ``Display text in boldface.'' @item +When a command is meaningful only in a certain mode or situation, +do mention that in the documentation string. For example, +the documentation of @code{dired-find-file} is: + +@example +In Dired, visit the file or directory named on this line. +@end example + +@item Do not start or end a documentation string with whitespace. @item Format the documentation string so that it fits in an Emacs window on an 80-column screen. It is a good idea for most lines to be no wider than -60 characters. The first line can be wider if necessary to fit the -information that ought to be there. +60 characters. The first line should not be wider than 67 characters +or it will look bad in the output of @code{apropos}. -However, rather than simply filling the entire documentation string, you -can make it much more readable by choosing line breaks with care. -Use blank lines between topics if the documentation string is long. +You can fill the text if that looks good. However, rather than blindly +filling the entire documentation string, you can often make it much more +readable by choosing certain line breaks with care. Use blank lines +between topics if the documentation string is long. @item @strong{Do not} indent subsequent lines of a documentation string so @@ -499,12 +509,16 @@ When a function's documentation string mentions the value of an argument of the function, use the argument name in capital letters as if it were a name for that value. Thus, the documentation string of the function -@code{/} refers to its second argument as @samp{DIVISOR}, because the -actual argument name is @code{divisor}. +@code{eval} refers to its second argument as @samp{FORM}, because the +actual argument name is @code{form}: -Also use all caps for metasyntactic variables, such as when you show -the decomposition of a list or vector into subunits, some of which may -vary. @samp{KEY} and @samp{VALUE} in the following example +@example +Evaluate FORM and return its value. +@end example + +Also write metasyntactic variables in capital letters, such as when you +show the decomposition of a list or vector into subunits, some of which +may vary. @samp{KEY} and @samp{VALUE} in the following example illustrate this practice: @example @@ -513,6 +527,18 @@ @end example @item +If a line in a documentation string begins with an open-parenthesis, +write a backslash before the open-parenthesis, like this: + +@example +The argument FOO can be either a number +\(a buffer position) or a string (a file name). +@end example + +This prevents the open-parenthesis from being treated as the start of a +defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). + +@item @iftex When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), with single-quotes @@ -634,29 +660,31 @@ @end group @end smallexample +We also normally use two semicolons for comments outside functions. + +@smallexample +@group +;; This Lisp code is run in Emacs +;; when it is to operate as a server +;; for other processes. +@end group +@end smallexample + Every function that has no documentation string (presumably one that is -used only internally within the package it belongs to), should have -instead a two-semicolon comment right before the function, explaining -what the function does and how to call it properly. Explain precisely -what each argument means and how the function interprets its possible -values. +used only internally within the package it belongs to), should instead +have a two-semicolon comment right before the function, explaining what +the function does and how to call it properly. Explain precisely what +each argument means and how the function interprets its possible values. @item ;;; Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. Such comments are used outside function definitions to -make general statements explaining the design principles of the program. -For example: - -@smallexample -@group -;;; This Lisp code is run in Emacs -;;; when it is to operate as a server -;;; for other processes. -@end group -@end smallexample +the left margin. These are used, occasionally, for comments within +functions that should start at the margin. We also use them sometimes +for comments that are between functions---whether to use two or three +semicolons there is a matter of style. Another use for triple-semicolon comments is for commenting out lines -within a function. We use triple-semicolons for this precisely so that +within a function. We use three semicolons for this precisely so that they remain at the left margin. @smallexample @@ -799,7 +827,8 @@ names---they have no standard meanings, so they can't do any harm. We use additional stylized comments to subdivide the contents of the -library file. Here is a table of them: +library file. These should be separated by blank lines from anything +else. Here is a table of them: @table @samp @item ;;; Commentary: @@ -815,11 +844,10 @@ @item ;;; Change Log: This begins change log information stored in the library file (if you -store the change history there). For most of the Lisp -files distributed with Emacs, the change history is kept in the file -@file{ChangeLog} and not in the source file at all; these files do -not have a @samp{;;; Change Log:} line. @samp{History} is an -alternative to @samp{Change Log}. +store the change history there). For Lisp files distributed with Emacs, +the change history is kept in the file @file{ChangeLog} and not in the +source file at all; these files generally do not have a @samp{;;; Change +Log:} line. @samp{History} is an alternative to @samp{Change Log}. @item ;;; Code: This begins the actual code of the program.