Commit d6d78511 authored by Chong Yidong's avatar Chong Yidong
Browse files

Lisp manaual improvements re docstrings

* doc/lispref/compile.texi (Docs and Compilation): Copyedits.

* doc/lispref/help.texi (Documentation, Accessing Documentation): Copyedits.
(Documentation Basics): Rewrite, avoiding a repeat discussion of
docstring conventions.

* doc/lispref/tips.texi (Documentation Tips): Move discussion of
emacs-lisp-docstring-fill-column here from Documentation Basics.
parent 0d53f628
2014-01-03 Chong Yidong <cyd@gnu.org>
* help.texi (Documentation, Accessing Documentation): Copyedits.
(Documentation Basics): Rewrite, avoiding a repeat discussion of
docstring conventions.
* tips.texi (Documentation Tips): Move discussion of
emacs-lisp-docstring-fill-column here from Documentation Basics.
* compile.texi (Docs and Compilation): Copyedits.
2014-01-02 Glenn Morris <rgm@gnu.org>
* numbers.texi (Numeric Conversions): Fix a typo.
......
......@@ -240,59 +240,49 @@ $ emacs -batch -f batch-byte-compile *.el
@section Documentation Strings and Compilation
@cindex dynamic loading of documentation
Functions and variables loaded from a byte-compiled file access their
documentation strings dynamically from the file whenever needed. This
saves space within Emacs, and makes loading faster because the
documentation strings themselves need not be processed while loading the
file. Actual access to the documentation strings becomes slower as a
result, but this normally is not enough to bother users.
When Emacs loads functions and variables from a byte-compiled file,
it normally does not load their documentation strings into memory.
Each documentation string is ``dynamically'' loaded from the
byte-compiled file only when needed. This saves memory, and speeds up
loading by skipping the processing of the documentation strings.
This feature has a drawback: if you delete, move, or alter the
compiled file (such as by compiling a new version), Emacs may no
longer be able to access the documentation string of previously-loaded
functions or variables. Such a problem normally only occurs if you
build Emacs yourself, and happen to edit and/or recompile the Lisp
source files. To solve it, just reload each file after recompilation.
Dynamic loading of documentation strings from byte-compiled files is
determined, at compile time, for each byte-compiled file. It can be
disabled via the option @code{byte-compile-dynamic-docstrings}.
Dynamic access to documentation strings does have drawbacks:
@defopt byte-compile-dynamic-docstrings
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
@itemize @bullet
@item
If you delete or move the compiled file after loading it, Emacs can no
longer access the documentation strings for the functions and variables
in the file.
To disable the dynamic loading feature for a specific file, set this
option to @code{nil} in its header line (@pxref{File Variables, ,
Local Variables in Files, emacs, The GNU Emacs Manual}), like this:
@item
If you alter the compiled file (such as by compiling a new version),
then further access to documentation strings in this file will
probably give nonsense results.
@end itemize
@smallexample
-*-byte-compile-dynamic-docstrings: nil;-*-
@end smallexample
@noindent
These problems normally occur only if you build Emacs yourself and use
it from the directory where you built it, and you happen to edit
and/or recompile the Lisp source files. They can be easily cured by
reloading each file after recompiling it.
This is useful mainly if you expect to change the file, and you want
Emacs sessions that have already loaded it to keep working when the
file changes.
@end defopt
@cindex @samp{#@@@var{count}}
@cindex @samp{#$}
The dynamic documentation string feature writes compiled files that
use a special Lisp reader construct, @samp{#@@@var{count}}. This
construct skips the next @var{count} characters. It also uses the
@samp{#$} construct, which stands for ``the name of this file, as a
string''. It is usually best not to use these constructs in Lisp source
files, since they are not designed to be clear to humans reading the
file.
You can disable the dynamic documentation string feature at compile
time by setting @code{byte-compile-dynamic-docstrings} to @code{nil};
this is useful mainly if you expect to change the file, and you want
Emacs processes that have already loaded it to keep working when the
file changes. You can do this globally, or for one source file by
specifying a file-local binding for the variable. One way to do that
is by adding this string to the file's first line:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
@end example
@defopt byte-compile-dynamic-docstrings
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
@end defopt
Internally, the dynamic loading of documentation strings is
accomplished by writing compiled files with a special Lisp reader
construct, @samp{#@@@var{count}}. This construct skips the next
@var{count} characters. It also uses the @samp{#$} construct, which
stands for ``the name of this file, as a string''. Do not use these
constructs in Lisp source files; they are not designed to be clear to
humans reading the file.
@node Dynamic Loading
@section Dynamic Loading of Individual Functions
......
......@@ -10,8 +10,13 @@
GNU Emacs has convenient built-in help facilities, most of which
derive their information from documentation strings associated with
functions and variables. This chapter describes how to access
documentation strings in Lisp programs. @xref{Documentation Tips},
for how to write good documentation strings.
documentation strings in Lisp programs.
The contents of a documentation string should follow certain
conventions. In particular, its first line should be a complete
sentence (or two complete sentences) that briefly describes what the
function or variable does. @xref{Documentation Tips}, for how to
write good documentation strings.
Note that the documentation strings for Emacs are not the same thing
as the Emacs manual. Manuals have their own source files, written in
......@@ -40,77 +45,48 @@ Help, emacs, The GNU Emacs Manual}.
@cindex string, writing a doc string
A documentation string is written using the Lisp syntax for strings,
with double-quote characters surrounding the text of the string. This
is because it really is a Lisp string object. The string serves as
documentation when it is written in the proper place in the definition
of a function or variable. In a function definition, the documentation
string follows the argument list. In a variable definition, the
documentation string follows the initial value of the variable.
When you write a documentation string, make the first line a
complete sentence (or two complete sentences) that briefly describes
what the function or variable does. Some commands, such as
@code{apropos}, show only the first line of a multi-line documentation
string. Also, you should not indent the second line of a
documentation string, if it has one, because that looks odd when you
use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
(@code{describe-variable}) to view the documentation string. There
are many other conventions for documentation strings; see
@ref{Documentation Tips}.
Documentation strings can contain several special text sequences,
referring to key bindings which are looked up in the current keymaps
when the user views the documentation. This allows the help commands
to display the correct keys even if a user rearranges the default key
bindings. @xref{Keys in Documentation}.
In the documentation string of an autoloaded command
(@pxref{Autoload}), these special text sequences have an additional
special effect: they cause @kbd{C-h f} (@code{describe-function}) on
the command to trigger autoloading. (This is needed for correctly
setting up the hyperlinks in the @file{*Help*} buffer).
@vindex emacs-lisp-docstring-fill-column
Emacs Lisp mode fills documentation strings to the width
specified by @code{emacs-lisp-docstring-fill-column}.
Exactly where a documentation string is stored depends on how its
function or variable was defined or loaded into memory:
@itemize @bullet
@item
@kindex function-documentation
When you define a function (@pxref{Lambda Expressions}, and
@pxref{Function Documentation}), the documentation string is stored in
the function definition itself. You can also put function
documentation in the @code{function-documentation} property of a
function name. That is useful for function definitions which can't
hold a documentation string, such as keyboard macros.
@item
@kindex variable-documentation
When you define a variable with a @code{defvar} or related form
(@pxref{Defining Variables}), the documentation is stored in the
variable's @code{variable-documentation} property.
with double-quote characters surrounding the text. It is, in fact, an
actual Lisp string. When the string appears in the proper place in a
function or variable definition, it serves as the function's or
variable's documentation.
@cindex @code{function-documentation} property
In a function definition (a @code{lambda} or @code{defun} form), the
documentation string is specified after the argument list, and is
normally stored directly in the function object. @xref{Function
Documentation}. You can also put function documentation in the
@code{function-documentation} property of a function name
(@pxref{Accessing Documentation}).
@cindex @code{variable-documentation} property
In a variable definition (a @code{defvar} form), the documention
string is specified after the initial value. @xref{Defining
Variables}. The string is stored in the variable's
@code{variable-documentation} property.
@cindex @file{DOC} (documentation) file
@item
To save memory, the documentation for preloaded functions and
variables (including primitive functions and autoloaded functions) is
not kept in memory, but in the file
@file{emacs/etc/DOC}).
@item
When a function or variable is loaded from a byte-compiled file during
the Emacs session, its documentation string is not loaded into memory.
Instead, Emacs looks it up in the byte-compiled file as needed.
@xref{Docs and Compilation}.
@end itemize
Sometimes, Emacs does not keep documentation strings in memory.
There are two such circumstances. Firstly, to save memory, the
documentation for preloaded functions and variables (including
primitives) is kept in a file named @file{DOC}, in the directory
specified by @code{doc-directory} (@pxref{Accessing Documentation}).
Secondly, when a function or variable is loaded from a byte-compiled
file, Emacs avoids loading its documentation string (@pxref{Docs and
Compilation}). In both cases, Emacs looks up the documentation string
from the file only when needed, such as when the user calls @kbd{C-h
f} (@code{describe-function}) for a function.
Documentation strings can contain special @dfn{key substitution
sequences}, referring to key bindings which are looked up only when
the user views the documentation. This allows the help commands to
display the correct keys even if a user rearranges the default key
bindings. @xref{Keys in Documentation}.
@noindent
Regardless of where the documentation string is stored, you can
retrieve it using the @code{documentation} or
@code{documentation-property} function, described in the next section.
In the documentation string of an autoloaded command
(@pxref{Autoload}), these key-substitution sequences have an
additional special effect: they cause @kbd{C-h f} on the command to
trigger autoloading. (This is needed for correctly setting up the
hyperlinks in the @file{*Help*} buffer.)
@node Accessing Documentation
@section Access to Documentation Strings
......@@ -122,18 +98,20 @@ most often used to look up the documentation strings of variables, for
which @var{property} is @code{variable-documentation}. However, it
can also be used to look up other kinds of documentation, such as for
customization groups (but for function documentation, use the
@code{documentation} command, below).
@code{documentation} function, below).
If the value recorded in the property list refers to a documentation
string stored in a @file{DOC} file or a byte-compiled
file, it looks up that string and returns it. If the property value
isn't @code{nil}, isn't a string, and doesn't refer to text in a file,
then it is evaluated as a Lisp expression to obtain a string.
If the property value refers to a documentation string stored in the
@file{DOC} file or a byte-compiled file, this function looks up that
string and returns it.
The last thing this function does is pass the string through
@code{substitute-command-keys} to substitute actual key bindings
(@pxref{Keys in Documentation}). However, it skips this step if
@var{verbatim} is non-@code{nil}.
If the property value isn't @code{nil}, isn't a string, and doesn't
refer to text in a file, then it is evaluated as a Lisp expression to
obtain a string.
Finally, this function passes the string through
@code{substitute-command-keys} to substitute key bindings (@pxref{Keys
in Documentation}). It skips this step if @var{verbatim} is
non-@code{nil}.
@smallexample
@group
......@@ -160,16 +138,18 @@ ordinary functions.
If @var{function} is a symbol, this function first looks for the
@code{function-documentation} property of that symbol; if that has a
non-@code{nil} value, the documentation comes from that value (if the
value is not a string, it is evaluated). If @var{function} is not a
symbol, or if it has no @code{function-documentation} property, then
@code{documentation} extracts the documentation string from the actual
function definition, reading it from a file if called for.
value is not a string, it is evaluated).
If @var{function} is not a symbol, or if it has no
@code{function-documentation} property, then @code{documentation}
extracts the documentation string from the actual function definition,
reading it from a file if called for.
Finally, unless @var{verbatim} is non-@code{nil}, it calls
@code{substitute-command-keys} so as to return a value containing the
actual (current) key bindings.
Finally, unless @var{verbatim} is non-@code{nil}, this function calls
@code{substitute-command-keys}. The result is the documentation
string to return.
The function @code{documentation} signals a @code{void-function} error
The @code{documentation} function signals a @code{void-function} error
if @var{function} has no function definition. However, it is OK if
the function definition has no documentation string. In that case,
@code{documentation} returns @code{nil}.
......@@ -180,7 +160,6 @@ This function returns the documentation string of @var{face} as a
face.
@end defun
@c Wordy to prevent overfull hboxes. --rjc 15mar92
Here is an example of using the two functions, @code{documentation} and
@code{documentation-property}, to display the documentation strings for
several symbols in a @file{*Help*} buffer.
......@@ -313,6 +292,7 @@ without actually installing it. @xref{Definition of data-directory}.
@cindex documentation, keys in
@cindex keys in documentation strings
@cindex substituting keys in documentation
@cindex key substitution sequence
When documentation strings refer to key sequences, they should use the
current, actual key bindings. They can do so using certain special text
......
......@@ -573,10 +573,13 @@ Format the documentation string so that it fits in an Emacs window on an
60 characters. The first line should not be wider than 67 characters
or it will look bad in the output of @code{apropos}.
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 sections if the documentation string is long.
@vindex emacs-lisp-docstring-fill-column
You can fill the text if that looks good. Emacs Lisp mode fills
documentation strings to the width specified by
@code{emacs-lisp-docstring-fill-column}. However, you can sometimes
make a documentation string much more readable by adjusting its line
breaks with care. Use blank lines between sections if the
documentation string is long.
@item
The first line of the documentation string should consist of one or two
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment