Commit 12008438 authored by Thien-Thi Nguyen's avatar Thien-Thi Nguyen
Browse files

Docstring style and grammar tweaks; nfc.

parent d2f00838
......@@ -117,17 +117,17 @@ DOC-STR should be a single line providing more information about the
REGEXP is a regular expression to match against the beginning of the file;
it should match only files in that format. Use nil to avoid
matching at all for formats for which this isn't appropriate to
matching at all for formats for which it isn't appropriate to
require explicit encoding/decoding.
FROM-FN is called to decode files in that format; it gets two args, BEGIN
FROM-FN is called to decode files in that format; it takes two args, BEGIN
and END, and can make any modifications it likes, returning the new
end. It must make sure that the beginning of the file no longer
matches REGEXP, or else it will get called again.
Alternatively, FROM-FN can be a string, which specifies a shell command
(including options) to be used as a filter to perform the conversion.
TO-FN is called to encode a region into that format; it is passed three
TO-FN is called to encode a region into that format; it takes three
arguments: BEGIN, END, and BUFFER. BUFFER is the original buffer that
the data being written came from, which the function could use, for
example, to find the values of local variables. TO-FN should either
......@@ -142,7 +142,7 @@ MODIFY, if non-nil, means the TO-FN wants to modify the region. If nil,
MODE-FN, if specified, is called when visiting a file with that format.
It is called with a single positive argument, on the assumption
that it turns on some Emacs mode.
that this would turn on some minor mode.
PRESERVE, if non-nil, means that `format-write-file' should not remove
this format from `buffer-file-formats'.")
......@@ -150,8 +150,8 @@ PRESERVE, if non-nil, means that `format-write-file' should not remove
;;; Basic Functions (called from Lisp)
(defun format-encode-run-method (method from to &optional buffer)
"Translate using function or shell script METHOD the text from FROM to TO.
If METHOD is a string, it is a shell command;
"Translate using METHOD the text from FROM to TO.
If METHOD is a string, it is a shell command (including options);
otherwise, it should be a Lisp function.
BUFFER should be the buffer that the output originally came from."
(if (stringp method)
......@@ -173,9 +173,9 @@ BUFFER should be the buffer that the output originally came from."
(funcall method from to buffer)))
(defun format-decode-run-method (method from to &optional buffer)
"Decode using function or shell script METHOD the text from FROM to TO.
If METHOD is a string, it is a shell command; otherwise, it should be
a Lisp function. Decoding is done for the given BUFFER."
"Decode using METHOD the text from FROM to TO.
If METHOD is a string, it is a shell command (including options); otherwise,
it should be a Lisp function. Decoding is done for the given BUFFER."
(if (stringp method)
(let ((error-buff (get-buffer-create "*Format Errors*"))
(coding-system-for-write 'no-conversion)
......@@ -200,15 +200,15 @@ a Lisp function. Decoding is done for the given BUFFER."
(defun format-annotate-function (format from to orig-buf format-count)
"Return annotations for writing region as FORMAT.
FORMAT is a symbol naming one of the formats defined in `format-alist',
it must be a single symbol, not a list like `buffer-file-format'.
FORMAT is a symbol naming one of the formats defined in `format-alist'.
It must be a single symbol, not a list like `buffer-file-format'.
FROM and TO delimit the region to be operated on in the current buffer.
ORIG-BUF is the original buffer that the data came from.
FORMAT-COUNT is an integer specifying how many times this function has
been called in the process of decoding ORIG-BUF.
This function works like a function on `write-region-annotate-functions':
This function works like a function in `write-region-annotate-functions':
it either returns a list of annotations, or returns with a different buffer
current, which contains the modified text to write. In the latter case,
this function's value is nil.
......@@ -253,7 +253,7 @@ If optional third arg VISIT-FLAG is true, set `buffer-file-format'
to the reverted list of formats used, and call any mode functions defined
for those formats.
Returns the new length of the decoded region.
Return the new length of the decoded region.
For most purposes, consider using `format-decode-region' instead."
(let ((mod (buffer-modified-p))
......@@ -312,9 +312,9 @@ For most purposes, consider using `format-decode-region' instead."
(defun format-decode-buffer (&optional format)
"Translate the buffer from some FORMAT.
If the format is not specified, this function attempts to guess.
`buffer-file-format' is set to the format used, and any mode-functions
for the format are called."
If the format is not specified, attempt a regexp-based guess.
Set `buffer-file-format' to the format used, and call any
format-specific mode functions."
(interactive
(list (format-read "Translate buffer from format (default guess): ")))
(save-excursion
......@@ -343,7 +343,7 @@ formats defined in `format-alist', or a list of such symbols."
(defun format-encode-region (beg end &optional format)
"Translate the region into some FORMAT.
FORMAT defaults to `buffer-file-format', it is a symbol naming
FORMAT defaults to `buffer-file-format'. It is a symbol naming
one of the formats defined in `format-alist', or a list of such symbols."
(interactive
(list (region-beginning) (region-end)
......@@ -374,9 +374,9 @@ Make buffer visit that file and set the format as the default for future
saves. If the buffer is already visiting a file, you can specify a directory
name as FILENAME, to write a file of the same old name in that directory.
If optional third arg CONFIRM is non-nil, this function asks for
confirmation before overwriting an existing file. Interactively,
confirmation is required unless you supply a prefix argument."
If optional third arg CONFIRM is non-nil, ask for confirmation before
overwriting an existing file. Interactively, confirmation is required
unless you supply a prefix argument."
(interactive
;; Same interactive spec as write-file, plus format question.
(let* ((file (if buffer-file-name
......@@ -419,7 +419,7 @@ If FORMAT is nil then do not do any format conversion."
"Insert the contents of file FILENAME using data format FORMAT.
If FORMAT is nil then do not do any format conversion.
The optional third and fourth arguments BEG and END specify
the part of the file to read.
the part (in bytes) of the file to read.
The return value is like the value of `insert-file-contents':
a list (ABSOLUTE-FILE-NAME SIZE)."
......@@ -456,10 +456,10 @@ Formats are defined in `format-alist'. Optional arg is the PROMPT to use."
(defun format-replace-strings (alist &optional reverse beg end)
"Do multiple replacements on the buffer.
ALIST is a list of (FROM . TO) pairs, which should be proper arguments to
`search-forward' and `replace-match' respectively.
Optional 2nd arg REVERSE, if non-nil, means the pairs are (TO . FROM), so that
you can use the same list in both directions if it contains only literal
strings.
`search-forward' and `replace-match', respectively.
Optional second arg REVERSE, if non-nil, means the pairs are (TO . FROM),
so that you can use the same list in both directions if it contains only
literal strings.
Optional args BEG and END specify a region of the buffer on which to operate."
(save-excursion
(save-restriction
......@@ -497,7 +497,7 @@ the value of `foo'."
(defun format-make-relatively-unique (a b)
"Delete common elements of lists A and B, return as pair.
Compares using `equal'."
Compare using `equal'."
(let* ((acopy (copy-sequence a))
(bcopy (copy-sequence b))
(tail acopy))
......@@ -511,9 +511,9 @@ Compares using `equal'."
(defun format-common-tail (a b)
"Given two lists that have a common tail, return it.
Compares with `equal', and returns the part of A that is equal to the
Compare with `equal', and return the part of A that is equal to the
equivalent part of B. If even the last items of the two are not equal,
returns nil."
return nil."
(let ((la (length a))
(lb (length b)))
;; Make sure they are the same length
......@@ -534,9 +534,9 @@ A proper list is a list ending with a nil cdr, not with an atom "
(null list)))
(defun format-reorder (items order)
"Arrange ITEMS to following partial ORDER.
Elements of ITEMS equal to elements of ORDER will be rearranged to follow the
ORDER. Unmatched items will go last."
"Arrange ITEMS to follow partial ORDER.
Elements of ITEMS equal to elements of ORDER will be rearranged
to follow the ORDER. Unmatched items will go last."
(if order
(let ((item (member (car order) items)))
(if item
......@@ -793,7 +793,7 @@ yet known.
;; next-single-property-change instead of text-property-not-all, but then
;; we have to see if we passed TO.
(defun format-property-increment-region (from to prop delta default)
"Over the region between FROM and TO increment property PROP by amount DELTA.
"In the region from FROM to TO increment property PROP by amount DELTA.
DELTA may be negative. If property PROP is nil anywhere
in the region, it is treated as though it were DEFAULT."
(let ((cur from) val newval next)
......@@ -810,7 +810,7 @@ in the region, it is treated as though it were DEFAULT."
(defun format-insert-annotations (list &optional offset)
"Apply list of annotations to buffer as `write-region' would.
Inserts each element of the given LIST of buffer annotations at its
Insert each element of the given LIST of buffer annotations at its
appropriate place. Use second arg OFFSET if the annotations' locations are
not relative to the beginning of the buffer: annotations will be inserted
at their location-OFFSET+1 \(ie, the offset is treated as the position of
......@@ -834,7 +834,7 @@ property is the name of the annotation that you want to use, as it is for the
(defun format-annotate-region (from to translations format-fn ignore)
"Generate annotations for text properties in the region.
Searches for changes between FROM and TO, and describes them with a list of
Search for changes between FROM and TO, and describe them with a list of
annotations as defined by alist TRANSLATIONS and FORMAT-FN. IGNORE lists text
properties not to consider; any text properties that are neither ignored nor
listed in TRANSLATIONS are warned about.
......@@ -975,9 +975,9 @@ either strings, or lists of the form (PARAMETER VALUE)."
"Return annotations for property PROP changing from OLD to NEW.
These are searched for in the translations alist TRANSLATIONS
(see `format-annotate-region' for the format).
If NEW does not appear in the list, but there is a default function, then that
function is called.
Returns a cons of the form (CLOSE . OPEN)
If NEW does not appear in the list, but there is a default function,
then call that function.
Return a cons of the form (CLOSE . OPEN)
where CLOSE is a list of annotations to close
and OPEN is a list of annotations to open.
......@@ -1016,7 +1016,7 @@ either strings, or lists of the form (PARAMETER VALUE)."
(format-annotate-atomic-property-change prop-alist old new)))))
(defun format-annotate-atomic-property-change (prop-alist old new)
"Internal function annotate a single property change.
"Internal function to annotate a single property change.
PROP-ALIST is the relevant element of a TRANSLATIONS list.
OLD and NEW are the values."
(let (num-ann)
......
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