master 3306e11107 5/5: Merge from origin/emacs-28

[Eli Zaretskii]

branch: master
commit 3306e11107595524bdde90482023077b69e6c733
Merge: ead9c9602c 1e4b04c540
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Merge from origin/emacs-28
    
    1e4b04c Improve documentation of filling and justification commands
    9fd396e * lisp/progmodes/subword.el (superword-mode): Doc fix.  (Bug#...
    e303cb1 Fix indexing of module functions that return complex types.
---
 doc/lispref/internals.texi |  4 ++--
 doc/lispref/text.texi      |  5 +++--
 lisp/progmodes/subword.el  |  4 ++--
 lisp/textmodes/fill.el     | 51 ++++++++++++++++++++++++++++++----------------
 4 files changed, 40 insertions(+), 24 deletions(-)

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index bc73ff28a6..0037922aed 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1637,7 +1637,7 @@ This function returns the value of a Lisp float specified 
by
 @var{arg}, as a C @code{double} value.
 @end deftypefn
 
-@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, 
emacs_value @var{arg})
+@deftypefn Function {struct timespec} extract_time (emacs_env *@var{env}, 
emacs_value @var{arg})
 This function, which is available since Emacs 27, interprets @var{arg}
 as an Emacs Lisp time value and returns the corresponding @code{struct
 timespec}.  @xref{Time of Day}.  @code{struct timespec} represents a
@@ -1942,7 +1942,7 @@ garbage-collected.  Don't run any expensive code in a 
finalizer,
 because GC must finish quickly to keep Emacs responsive.
 @end deftypefn
 
-@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value 
@var{arg})
+@deftypefn Function {void *}get_user_ptr (emacs_env *@var{env}, emacs_value 
@var{arg})
 This function extracts the C pointer from the Lisp object represented
 by @var{arg}.
 @end deftypefn
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 37cf376bd5..7897adeb05 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1731,8 +1731,9 @@ filling when @var{justify} is non-@code{nil}.
 
 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
 other than line breaks untouched.  If @var{squeeze-after} is
-non-@code{nil}, it specifies a position in the region, and means don't
-canonicalize spaces before that position.
+non-@code{nil}, it specifies a position in the region, and means
+that whitespace other than line breaks should be left untouched before
+that position.
 
 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
 choose a fill prefix by default.  @xref{Adaptive Fill}.
diff --git a/lisp/progmodes/subword.el b/lisp/progmodes/subword.el
index b1b78b4d12..e06eb9a6f7 100644
--- a/lisp/progmodes/subword.el
+++ b/lisp/progmodes/subword.el
@@ -264,8 +264,8 @@ Optional argument ARG is the same as for `capitalize-word'."
   "Toggle superword movement and editing (Superword mode).
 
 Superword mode is a buffer-local minor mode.  Enabling it changes
-the definition of words such that symbols characters are treated
-as parts of words: e.g., in `superword-mode',
+the definition of words such that characters which have symbol
+syntax are treated as parts of words: e.g., in `superword-mode',
 \"this_is_a_symbol\" counts as one word.
 
 \\{superword-mode-map}"
diff --git a/lisp/textmodes/fill.el b/lisp/textmodes/fill.el
index 87cea5216a..d3c832a40d 100644
--- a/lisp/textmodes/fill.el
+++ b/lisp/textmodes/fill.el
@@ -644,20 +644,27 @@ The break position will be always after LINEBEG and 
generally before point."
 
 (defun fill-region-as-paragraph (from to &optional justify
                                      nosqueeze squeeze-after)
-  "Fill the region as one paragraph.
-It removes any paragraph breaks in the region and extra newlines at the end,
-indents and fills lines between the margins given by the
-`current-left-margin' and `current-fill-column' functions.
-\(In most cases, the variable `fill-column' controls the width.)
-It leaves point at the beginning of the line following the paragraph.
-
-Normally performs justification according to the `current-justification'
-function, but with a prefix arg, does full justification instead.
-
-From a program, optional third arg JUSTIFY can specify any type of
-justification.  Fourth arg NOSQUEEZE non-nil means not to make spaces
-between words canonical before filling.  Fifth arg SQUEEZE-AFTER, if non-nil,
-means don't canonicalize spaces before that position.
+  "Fill the region as if it were a single paragraph.
+This command removes any paragraph breaks in the region and
+extra newlines at the end, and indents and fills lines between the
+margins given by the `current-left-margin' and `current-fill-column'
+functions.  (In most cases, the variable `fill-column' controls the
+width.)  It leaves point at the beginning of the line following the
+region.
+
+Normally, the command performs justification according to
+the `current-justification' function, but with a prefix arg, it
+does full justification instead.
+
+When called from Lisp, optional third arg JUSTIFY can specify any
+type of justification; see `default-justification' for the possible
+values.
+Optional fourth arg NOSQUEEZE non-nil means not to make spaces
+between words canonical before filling.
+Fifth arg SQUEEZE-AFTER, if non-nil, should be a buffer position; it
+means canonicalize spaces only starting from that position.
+See `canonically-space-region' for the meaning of canonicalization
+of spaces.
 
 Return the `fill-prefix' used for filling.
 
@@ -1104,6 +1111,10 @@ space does not end a sentence, so don't break a line 
there."
 (defcustom default-justification 'left
   "Method of justifying text not otherwise specified.
 Possible values are `left', `right', `full', `center', or `none'.
+The values `left' and `right' mean lines are lined up at,
+respectively, left or right margin, and ragged at the other margin.
+`full' means lines are lined up at both margins.  `center' means each
+line is centered.  `none' means no justification or centering.
 The requested kind of justification is done whenever lines are filled.
 The `justification' text-property can locally override this variable."
   :type '(choice (const left)
@@ -1133,6 +1144,7 @@ However, it returns nil rather than `none' to mean 
\"don't justify\"."
 (defun set-justification (begin end style &optional whole-par)
   "Set the region's justification style to STYLE.
 This commands prompts for the kind of justification to use.
+See `default-justification' for the possible values and their meaning.
 If the mark is not active, this command operates on the current paragraph.
 If the mark is active, it operates on the region.  However, if the
 beginning and end of the region are not at paragraph breaks, they are
@@ -1184,7 +1196,8 @@ If the mark is not active, this applies to the current 
paragraph."
 
 (defun set-justification-left (b e)
   "Make paragraphs in the region left-justified.
-This means they are flush at the left margin and ragged on the right.
+This means lines are flush (lined up) at the left margin and ragged
+on the right.
 This is usually the default, but see the variable `default-justification'.
 If the mark is not active, this applies to the current paragraph."
   (interactive (list (if mark-active (region-beginning) (point))
@@ -1193,7 +1206,8 @@ If the mark is not active, this applies to the current 
paragraph."
 
 (defun set-justification-right (b e)
   "Make paragraphs in the region right-justified.
-This means they are flush at the right margin and ragged on the left.
+This means lines are flush (lined up) at the right margin and ragged
+on the left.
 If the mark is not active, this applies to the current paragraph."
   (interactive (list (if mark-active (region-beginning) (point))
                     (if mark-active (region-end) (point))))
@@ -1201,7 +1215,7 @@ If the mark is not active, this applies to the current 
paragraph."
 
 (defun set-justification-full (b e)
   "Make paragraphs in the region fully justified.
-This makes lines flush on both margins by inserting spaces between words.
+This makes lines be lined up on both margins by inserting spaces between words.
 If the mark is not active, this applies to the current paragraph."
   (interactive (list (if mark-active (region-beginning) (point))
                     (if mark-active (region-end) (point))))
@@ -1236,7 +1250,8 @@ If the mark is not active, this applies to the current 
paragraph."
 Normally does full justification: adds spaces to the line to make it end at
 the column given by `current-fill-column'.
 Optional first argument HOW specifies alternate type of justification:
-it can be `left', `right', `full', `center', or `none'.
+it can be `left', `right', `full', `center', or `none'; for their
+meaning, see `default-justification'.
 If HOW is t, will justify however the `current-justification' function says to.
 If HOW is nil or missing, full justification is done by default.
 Second arg EOP non-nil means that this is the last line of the paragraph, so