Fix horizontal line display in Custom buffers

* lisp/cus-edit.el (custom-group-value-create): Insert a newline
before calling 'custom-group--draw-horizontal-line'.  (Bug#39074)

; * etc/NEWS: Fix a typo.

flymake: fix typo in variable binding (bug#38752)

This mistake was found by an experimental elisp optimiser.

* lisp/progmodes/flymake-proc.el (flymake-proc-stop-all-syntax-checks):
Add missing brackets.

; Minor spelling fixes

* doc/emacs/anti.texi (Antinews): Minor spelling fixes.

Update Antinews in the Emacs manual

* doc/emacs/anti.texi (Antinews): Rewrite for Emacs 27.
* doc/emacs/emacs.texi (Top): Update the "Antiniews" item of the
top-level menu.

Use NSNumber instead of BOOL (bug#39047)

* src/nsfns.m (ns_set_represented_filename): Use correct type.

Copyright-paperwork-exempt: yes

Add comment on fido-mode's file-sorting semantics

* lisp/icomplete.el (icomplete--sorted-completions): Add comment.

Consider non-string minibuffer-default in icomplete

Fixes: bug#38992
* lisp/icomplete.el (icomplete--sorted-completions): Consider
non-string minibuffer-default.

Fix another compilation problem in a build without threads

* src/systhread.c (sys_thread_set_name) [!THREADS_ENABLED]: Add
a trivial implementation.

Fix build without threads

* src/systhread.c (sys_thread_create) [!THREADS_ENABLED]: Update
the function's signature to match prototype.  Reported by Glenn
Morris <rgm@gnu.org>.  (Bug#38632)

Fix compression of directories in Dired

This fixes comporession and uncompression of directories on
MS-Windows, but also on other systems.  The original code used
":" as the REGEXP of the directory entry in
dired-compress-file-suffixes, which on Windows always matched any
absolute file name, and can also match unusual file names on Posix
hosts.  This false match would cause dired-compress-file to act as
if we are decompressing a directory, but use a command suitable
for compression, which would fail in interesting ways.
We now use a REGEXP that can never match any valid file name.

* lisp/dired-aux.el (dired-compress-file-suffixes): Make the
"compress directory" entry's REGEXP really fail to match any valid
file name.
(dired-compress-file): Adapt to the change in
dired-compress-file-suffixes.  (Bug#39024)
(dired-compress): If the current file is a directory, or if the
uncompressed file is a directory, don't remove the original from
the listing, since it is left in the filesystem.

; * etc/NEWS: Review of the whole text.

Further enhancement on `tramp-file-local-name'

* lisp/net/tramp.el (tramp-file-local-name): Call `file-local-name'
if NAME is not a Tramp file name.

Objective C Mode imenu: cease recognizing "functions" within comments, etc.

This fixes bug #38749.

* lisp/progmodes/cc-menus.el (cc-imenu-objc-function): Put a c-literal-limits
test around the innards of the main re-search-backward loop.

; * etc/NEWS: Update the text about the XDG_CONFIG_HOME/emacs behavior.

Fix BSD and macOS builds w.r.t. pthread_setname_np (bug#38632)

pthread_setname_np takes only a single argument on BSD and macOS,
and affects the current thread only.

* configure.ac: Add check for single-argument pthread_setname_np
* src/systhread.c (sys_thread_set_name): New (w32 and pthread versions).
(sys_thread_create): Remove name argument and name-setting.
(w32_beginthread_wrapper): Remove name-setting.
* src/systhread.h (sys_thread_create, sys_thread_set_name):
Update prototypes.
* src/thread.c (run_thread): Call sys_thread_set_name.
(Fmake_thread): Adapt call to sys_thread_create.
* src/thread.h (struct thread_state): Adjust comment.

Scale top-left coordinates in display-monitor-attributes-list

When using multiple monitors, and HiDPI, the top-left coordinates of
the monitors need to be adjusted, not just the width and height
(Bug#31223).

* xfns.c (Fx_display_monitor_attributes_list): Scale top-left
coordinates.

xref-matches-in-files: Big Tramp speed-up

* lisp/progmodes/xref.el (xref-matches-in-files):
Greatly improve performance with remote files using Tramp
(bug#34343).

* lisp/net/tramp.el (tramp-file-local-name): Remove `save-match-data'.

Fix rendering bug due to unsynchronized cairo surface size (Bug#38497)

* src/xterm.c (handle_one_xevent) <ConfigureNotify> [USE_CAIRO && !USE_GTK]:
Call x_cr_update_surface_desired_size for a related frame as a fallback.

Avoid crash by access to cleared img->pixmap->data/img->mask->data (Bug#38774)

* src/image.c (prepare_image_for_display) [USE_CAIRO]: Call IMAGE_BACKGROUND
and IMAGE_BACKGROUND_TRANSPARENT.

Avoid assertion violations in very small-height windows

* src/xdisp.c (try_cursor_movement, redisplay_window)
(row_containing_pos): Skip tab-line glyph rows in addition to
header-line rows, when working on the top-most glyph row of a
window.  This avoids assertion violations in set_cursor_from_row.
(Bug#38966)

Use pthread_setname_np to set thread name

* configure.ac: Remove check for sys/prctl.h and prctl, check for
pthread_setname_np instead.

* systhread.c: Remove sys/prctl.h include.
(sys_thread_create) [HAVE_PTHREAD_SETNAME_NP]: Use pthread_setname_np
to set the name of the newly created thread (Bug#38632).

* thread.c (Fmake_thread): Use ENCODE_SYSTEM instead of
ENCODE_UTF_8 on the thread name.

Move “Fix some broken conditional forms” to master

Revert 2020-01-04T19:17:12Z!eggert@cs.ucla.edu
which recently I installed into the emacs-27 branch by mistake.
These patches are now on master instead (via merging).
Do not merge to master.

Improve doc-strings of 'quit-window' and 'quit-restore-window' (Bug#38819)

* lisp/window.el (quit-restore-window, quit-window): Make
doc-strings more consistent; add references to corresponding
section of the Elisp manual (Bug#38819).

Fix MH-E bug #470: Show buffer discards text properties

* lisp/mh-e/mh-show.el (mh-display-msg): reset font lock and set
major mode *before* formatting message content.  This changes lets
fonts work when the Show buffer is reused for a new message.
(mh-show-mode): no longer set buffer-read-only; that is better done
by mh-display-msg after setting all content.

Fix some broken conditional forms

Problem reported by Mattias Engdegård in:
https://lists.gnu.org/r/emacs-devel/2020-01/msg00088.html
* lisp/cedet/ede/cpp-root.el (ede-create-lots-of-projects-under-dir):
Remove this quick hack, which didn’t do anything anyway.
* lisp/cedet/ede/pconf.el (ede-proj-configure-test-required-file):
* lisp/emacs-lisp/tabulated-list.el (tabulated-list-print-col):
* lisp/net/nsm.el (nsm-check-tls-connection):
Use ‘when’ rather than bypassing it.  This doesn’t affect behavior
and is better style.
* lisp/cedet/srecode/semantic.el (srecode-semantic-handle-:tag):
Fix typo that suppressed an error.
* lisp/filesets.el (filesets-run-cmd): Fix typo that mishandled spacing.
* lisp/gnus/gnus-cloud.el (gnus-cloud-update-newsrc-data):
Fix typo that caused “GROUP has older different info in the cloud
as of DATE, update it here?” prompt result to always be treated as
“yes”.
* lisp/gnus/mml-smime.el (mml-smime-openssl-encrypt): Simplify,
since smime-encrypt-buffer signals error on failure.
* lisp/international/titdic-cnv.el (tsang-quick-converter): Simplify.
The conversion of this file to utf-8-emacs in
2019-01-08T02:18:40Z!monnier@iro.umontreal.ca removed the
distinction between Big5 and CNS fulltitles in the generated docstring.
* lisp/org/org-agenda.el (org-agenda-show-and-scroll-up):
* lisp/textmodes/table.el (table--generate-source-cell-contents):
Simplify by removing useless code.
* lisp/org/ox-odt.el (org-odt--format-timestamp): Fix typo that
always output time-of-day even when the timestamp lacked it.

Fix a scoping error in tramp-sudoedit.el

* lisp/net/tramp-sudoedit.el (tramp-sudoedit-handle-file-system-info):
Fix a scoping error.

* lisp/autorevert.el (auto-revert-notify-handler): Fix bracketing.

Fix typo in 'window_box_height'

* src/xdisp.c (window_box_height): Add missing 'else'.

Install g++ for CEDET tests

* .gitlab-ci.yml (before_script): Add g++.
Backport from master.

* lisp/net/tramp.el: Fix typos.

* lisp/net/tramp.el (tramp-file-local-name): New defun.  (Bug#34343)

Adapt commentary in Tramp persistency file

* lisp/net/tramp-cache.el (tramp-dump-connection-properties):
Adapt commentary in `tramp-persistency-file-name'.

Change Tramp version to 2.4.3.27.1

* doc/misc/trampver.texi:
* lisp/net/trampver.el: Change version to "2.4.3.27.1".
(customize-package-emacs-version-alist): Add Tramp version
integrated in Emacs 27.1.

; * src/dispnew.c (adjust_glyph_matrix): Fix last change.

Fix redisplay when mode-line-format changes mode-line's height

* lisp/frame.el (top-level): Add mode-line-format,
tab-line-format, and header-line-format to the list of variables
that should trigger an immediate redisplay of the buffer's
window.  This fixes redisplay of windows when the mode line
changes its height.

* src/xdisp.c (window_box_height): Use the window's
mode_line_height, tab_line_height, and header_line_height fields
in preference to CURRENT_MODE_LINE_HEIGHT,
CURRENT_TAB_LINE_HEIGHT, and CURRENT_HEADER_LINE_HEIGHT,
respectively.  This fixes display of vertical scroll bar when the
height of the window's mode line changes.
* src/dispnew.c (adjust_glyph_matrix): When resizing a window's
matrix, reset the mode_line_p flag of the previous mode-line row,
so that the window_box_height, CURRENT_MODE_LINE_HEIGHT, and their
ilk won't use stale info.  (Bug#38828)

* src/fileio.c (Fwrite_region): Improve the doc string.

Fix removal of frame decorations on Windows (Bug#38705)

* src/w32fns.c (w32_set_undecorated): Actualize
f->output_data.w32->dwStyle for subsequent calls of
AdjustWindowRect (Bug#38705).
* src/w32term.h (struct w32_output): Add comment for
dwstyle slot.

Fix compilation with GTK versions older than 3

* src/xfns.c (x_get_net_workarea): Change a recently moved #ifndef
so that GTK builds which need this function will compile it.
Reported by John <jpff@codemist.co.uk>.

(cherry picked from commit d36adb544d984b91c70f6194da01344e4b2b6fc9)

Fix reverting customizations

* lisp/custom.el (custom-push-theme): Don't use setcar to modify
the recorded value of PROP; instead, cons a new property list by
deleting the old value and adding the new one.  (Bug#38812)

* lisp/loadup.el: Set max-specpdl-size to 1800 when loading cl-generic.el.

Revert "Raise default max-specpdl-size value"

This reverts commit bb9402e6e9c12938aee31b81e25511eb1f6335d2.

; Fix NEWS.24

* etc/NEWS.24: Minor retroactive wording changes and additions to
fix the version shown by Help commands.  (Bug#38844)

Raise default max-specpdl-size value

Occasionally, loading cl-generic.el from source requires
max_specpdl_size > 1600 when bootstrapping, and thus fails.
In any case we are very close to the limit.

* src/eval.c (init_eval_once): Raise max_specpdl_size to 1800.
* doc/lispref/variables.texi (Local Variables): Update docs.

; Auto-commit of loaddefs files.

Update distribution documentation

* admin/nt/README-ftp-server: Remove as obsolete
* admin/nt/dist-build/README-windows-binaries: Add information
  about installer

Pacify gcc -Wunused-function on Ubuntu 18.04.3

This improves on 2019-12-25T20:01:07Z!eggert@cs.ucla.edu,
by fixing a GCC warning on Ubuntu 18.04.3
“‘x_get_net_workarea’ defined but not used”.
* src/xfns.c (x_get_net_workarea) [!USE_GTK]: Do not define.

Fix copyright years by hand

These are dates that admin/update-copyright did not update.

Update copyright year to 2020

Run "TZ=UTC0 admin/update-copyright $(git ls-files)".

; * etc/NEWS: Make the description of XDG fallback more accurate.

Don't always resort in recently introduced icomplete--sorted-completions

Doing so breaks icomplete-forward-completions and
icomplete-backward-completions.

* lisp/icomplete.el (icomplete--sorted-completions): Don't always
resort.

(cherry picked from commit 639fb50ed4c622f99dfbde32fbdbca42ce36d385)

Don't force completion recalculation in icomplete-fido-ret

Besides the adverse effect of delaying completions, it tripped up the
useful logic of icomplete-force-complete-and-exit in the case where a
default was available, but no completions calculated yet.

* lisp/icomplete.el (icomplete-fido-ret): Don't force calculation
of completions.

(cherry picked from commit 13778aa5be7bf028893672d84c2a291f491d8216)

Correctly cache sorted completions in icomplete--sorted-completions

* lisp/icomplete.el (icomplete--sorted-completions): Use
completion--cache-all-sorted-completions.

(cherry picked from commit 83587bb68830bd91124f99ddf8590d1d5f63869f)

Move flex style's minibuffer-default-aware sorting to lisp/icomplete.el

This moves the logic from the series of commits starting in the commit named:

  Improve sorting of flex completion style with non-nil minibuffer-default

to lisp/icomplete.el, so far the only confirmed beneficiary of that
functionality.

* lisp/icomplete.el (icomplete--sorted-completions): Consider
minibuffer-default here.

* lisp/minibuffer.el (completion--flex-adjust-metadata): Simplify.

(cherry picked from commit 0d2a711dc9a65dc8eb6e995369e70cddbcd7d9a4)

Make fido-mode behave more like ido-mode when finding directories

Notably C-x d (M-x dired) and C-x v d (M-x vc-dir) behaved quite
differently, having regular files as the default instead of ido's
usual "./".

* lisp/icomplete.el (icomplete--sorted-completions): New helper.
(icomplete-completions): Use it.

(cherry picked from commit ee914051fbb4fbff9073a23b5ea7668bf48b5c6a)

Slightly simplify lisp/icomplete.el with new icomplete--category helper

* lisp/icomplete.el (icomplete-fido-kill)
(icomplete-fido-delete-char, icomplete-fido-ret)
(icomplete-fido-backward-updir, icomplete-exhibit): Use
icomplete--category.
(icomplete--category): New helper.

(cherry picked from commit 24a1f520f91c278cb8cc57325ea80285a3b252cf)

Another adjustment to flex completion style's sorting function

* lisp/minibuffer.el (completion--flex-adjust-metadata): Adjust
case when minibuffer-default is non-nil.

(cherry picked from commit 9c912049927cfb18b9c8b37039b38ddf51f2fe81)

; * test/lisp/calc/calc-tests.el: Fix warnings

Make minibuffer-tests work in out-of-tree builds (bug#38816)

* test/lisp/minibuffer-tests.el (completion-table-test-quoting):
Set default-directory.

Make comint-tests more robust (bug#38813)

* test/lisp/comint-tests.el (comint-test-no-password-function)
(comint-test-password-function-with-value)
(comint-test-password-function-with-nil):
Call accept-process-output as many times as needed, with a slightly
more generous timeout (100 ms), after sending the Password: prompt to
the process, since there must be time for some back-and-forth
communication.  Also clear the process-query-on-exit flag, since it
doesn't go well with noninteractive tests.

Fix tar-mode reading the oldgnu Tar format

This makes sure an entry for a long file name will not
accidentally appear as a directory, and thus its size will be
disregarded, causing corrupted file headers for all the subsequent
entries.  The original problem happened because the long file name
truncated to 99 bytes happened to end in a slash, which tar-mode
takes to be the indication of a directory.
* lisp/tar-mode.el (tar-header-block-tokenize): Accept an
additional argument DISABLE-SLASH; if non-nil, don't set the
link-type field of the descriptor to 5 (meaning a directory) just
because the name ends in a slash.  Use this argument when calling
itself recursively, to read the entry of the file with a long
name.  Set the link-type to 5 if the long name ends in a slash.
(Bug#38777)

Ensure mini-window is resized to show active minibuffer contents

* src/keyboard.c (read_char, command_loop_1): Resize the
mini-window after clearing the echo area while minibuffer is
active.  (Bug#38645)

Fix mini-window resizing under resize-mini-windows = t

* src/window.c (grow_mini_window): Fix resizing of mini-window
when the echo area is cleared, and the caller asks for the
mini-window to have zero lines.  (Bug#38791)

Fixes for makeinfo 4.13

* doc/lispref/customize.texi (Variable Definitions): Fix xref.
* doc/lispref/internals.texi (Writing Emacs Primitives)
(Module Values): Follow xref with comma.

; fix previous NEWS entry

Fix crash under -nw on macOS properly this time

* src/dispextern.h (FACE_COLOR_TO_PIXEL): Only use
ns_color_index_to_rgba when we're running under the NS gui
(Bug#38564).

Revert "Check for GUI frame in ns_color_index_to_rgba"

This reverts commit ea84a95bd8d43612b4a424fb93de25a68ac31d05.

Ignore all color fonts when using XFT

* etc/NEWS: Announce change to matching color fonts when using XFT.

* src/ftfont.c (ftfont_list) [HAVE_XFT && FC_COLOR]: Query for the
color attribute of the matched font, and skip it if it is not
FcFalse (Bug#37786).

Avoid unbounded growth of cl-random-state components (bug#38753)

* lisp/emacs-lisp/cl-extra.el (cl-random):
Perform the modulo 2**23 operation before updating the state instead
of after.  The result is always the same, but it prevents the state
from growing into arbitrary large bignums.

Patch from Christopher Wellons.

Sync with Tramp 2.4.3

* doc/misc/trampver.texi:
* lisp/net/trampver.el: Change version to "2.4.3".

* lisp/net/tramp.el: Bump version.
(tramp-handle-shell-command): The temp file for error-buffer is remote.

* test/lisp/net/tramp-tests.el (tramp-test30-make-process):
Simplify buffer generation.
(tramp-test32-shell-command): Extend test.

; xref-references-in-directory: Autoload as well

Fix up requires

* lisp/progmodes/project.el (project-files):
Remove (require 'xref).
(project--files-in-directory): Add it here instead.
(project-find-regexp, project-or-external-find-regexp): And here.
For 'xref--show-xrefs'.

Extract xref-matches-in-files from project--find-regexp-in-files

* lisp/progmodes/xref.el (xref-matches-in-files): Extract from
project--find-regexp-in-files.

* lisp/dired-aux.el (dired-do-find-regexp): Also use it here.

Rename xref-collect-references and xref-collect-matches

* lisp/progmodes/xref.el (xref-references-in-directory): Rename
from xref-collect-references.  Update the sole caller.
(xref-matches-in-directory): Rename from xref-collect-matches.
Update all callers (all of them are in the /tests/ dir).

* test/lisp/progmodes/xref-tests.el (xref-tests-data-dir):
Don't use the EMACS_TEST_DIRECTORY env var. It doesn't work when
running interactively.

; Improve the docstring some more

Improve docstrings

* lisp/progmodes/xref.el (xref-collect-matches)
(xref-collect-references): Improve docstrings.

Fix when expose draws partially visible first glyph (bug#38731)

* src/xdisp.c (expose_area): When the face extends to the end of the
line draw text from the correct x coordinate.

Don't require semantic/fw

* lisp/progmodes/xref.el (xref-collect-matches): Don't require
semantic/fw, we haven't been using semantic-find-file-noselect
here for a while.

Do some renames for clarity

* lisp/progmodes/xref.el (xref--last-file-buffer):
Rename from xref--last-visiting-buffer.  Update users.
(xref--find-file-buffer): Rename from xref--find-buffer-visiting
to match the standard function that gets called inside.  Ditto.

Rearrange NEWS, add missing documentation

* etc/NEWS: Rearrange and mark entries whether documented or not.

* doc/lispref/streams.texi (Output Variables): Document the new
default of 'print-quoted'.
* doc/lispref/keymaps.texi (Functions for Key Lookup): Document
that KEYMAP arg to 'lookup-key' can also be a list.
* doc/lispref/customize.texi (Variable Definitions): Document the
:local keyword of 'defcustom'.
* doc/lispref/numbers.texi (Float Basics): Document changes in
'logb'.
* doc/lispref/hooks.texi (Standard Hooks): Document
'comint-password-function'.

* doc/emacs/display.texi (Text Scale): Document text-size
adjustment using the mouse wheel.
* doc/emacs/frames.texi (Mouse Commands): Document image scaling
with the mouse wheel.
* doc/emacs/windows.texi (Window Convenience): Document
'global-tab-line-mode'.
* doc/emacs/search.texi (Repeat Isearch, Symbol Search)
(Isearch Yank): Document the new support for numeric arguments in
Isearch commands.
(Special Isearch): Document 'M-s M->' and 'M-s M-<'.
(Search Customizations): Document 'isearch-lazy-count'.  Improve
indexing.
(Not Exiting Isearch): Document the new value of
'isearch-allow-scroll'.
* doc/emacs/maintaining.texi (Xref Commands): Document the new 'g'
key binding.
* doc/emacs/package.texi (Package Installation): Document changes
in 'package-check-signature'.
* doc/emacs/maintaining.texi (VC Change Log): Document
'vc-log-search'.
* doc/emacs/dired.texi (Operating on Files): Document
'dired-vc-rename'.

Fix interactive spec in netrc-parse

* lisp/net/netrc.el (netrc-parse): Fix placement of interactive
spec (bug#38773).

Fix documentation of define-obsolete-* functions

* doc/lispref/functions.texi (Obsolete Functions): Make
documentation of functions that obsolete symbols match the
advertised calling conventions.

* lisp/emacs-lisp/byte-run.el (define-obsolete-function-alias)
(define-obsolete-variable-alias, define-obsolete-face-alias):
State in the doc strings that WHEN is a mandatory argument, to be
consistent with the advertised calling convention.  (Bug#38675)

Fix recent gnus-start.el breakage

* lisp/gnus/gnus-start.el (gnus-group-change-level): Fix previous
patch that made info nil when adding new groups (thereby making
gnus-newsrc-alist invalid).

(xref--find-buffer-visiting): Speed up by using get-file-buffer

* lisp/progmodes/xref.el (xref--find-buffer-visiting):
Speed up by using get-file-buffer.
(xref--collect-matches): Remove the condition on remote-id.
(https://lists.gnu.org/archive/html/emacs-devel/2019-12/msg00753.html)

project--vc-list-files: Recurse into submodules

* lisp/progmodes/project.el (project-try-vc): Do not treat a Git
submodule as a project root, go up to the parent repo.
(project--git-submodules): New function.
(project--vc-list-files): Use it.  Recurse into submodules.

Merge branch 'emacs-27' of git.savannah.gnu.org:/srv/git/emacs into emacs-27

Minor improvements of buffer documentation

* doc/emacs/buffers.texi (Buffers): Say that buffers are killed
when no longer needed.  Suggested by Jean-Christophe Helary
<jean.christophe.helary@traduction-libre.org>.

xref--collect-matches: Speed up on remote

* lisp/progmodes/xref.el (xref--collect-matches):
Don't call find-buffer-visiting on remote file names, it's pretty
slow (bug#34343).

; project--find-regexp-in-files: Avoid prepending remote-id twice (bug#34343)

; Use regexp type in tramp-adb-prompt (backport, do not merge)

* lisp/net/tramp-adb.el (tramp-adb-prompt): Use 'regexp' instead
of 'string' as type for values that are regexps in defcustom
declarations.

Fix installer build

* admin/nt/dist-build/build-zips.sh: Ensure that NSIS build always
  uses the actual build number to locate its files.

Update Windows build documentation

* admin/nt/dist-build/README-scripts: Update with branch and snapshot
  information.

Calc: add missing dynamic variable declarations

* lisp/calc/calc-alg.el (math-simplify-only, calc-simplify-mode)
(math-expand-formulas, calc-poly-div-remainder)
(math-living-dangerously, math-simplifying, calc-angle-mode)
(calc-prefer-frac, math-poly-base-variable):
Declare dynamic variables.
* test/lisp/calc/calc-tests.el (calc-poly-div):
Add test for at least one bug caused by missing declarations.

* doc/emacs/buffers.texi (Kill Buffer): Improve indexing.

Speed up dired-do-find-regexp

* lisp/dired-aux.el (dired-do-find-regexp): Speed up (bug#36857).
Previously, 'find' was called for every marked file (for plain
files and directories both).  Now 'find' is only called for
directories.

; Remove outdated declarations

; Clarify the assumption

project--find-regexp-in-files: Support remote files

* lisp/progmodes/project.el (project--find-regexp-in-files):
Support remote files (bug#34343).

Document some restrictions for module functions.

* doc/lispref/internals.texi (Module Functions): Document some
restrictions for module functions.