A function or macro body consisting of a single string literal now only
uses it as a return value.  Previously, it had the dual uses as return
value and doc string, which was never what the programmer wanted and
had some inconvenient consequences (bug#69387).

This change applies to `lambda`, `defun`, `defsubst` and `defmacro`
forms; most other defining forms already worked in the sensible way.

* lisp/emacs-lisp/bytecomp.el (byte-compile-lambda):
Don't use a lone string literal as doc string.
* test/lisp/emacs-lisp/bytecomp-resources/warn-wide-docstring-defun.el
(foo): Update docstring warning test.
* doc/lispref/functions.texi (Function Documentation): Update.
* etc/NEWS: Announce.

This warning is much more appropriate for the compiler, since lexical
binding affects what it can reason and warn about, than for checkdoc
as the warning has no bearing to documentation at all.
The move also improves the reach of the warning.

* etc/NEWS: Update.
* lisp/emacs-lisp/checkdoc.el (checkdoc-lexical-binding-flag)
(checkdoc-file-comments-engine): Move warning from here....
* lisp/emacs-lisp/bytecomp.el (byte-compile-file): ...to here.
* test/lisp/emacs-lisp/bytecomp-resources/no-byte-compile.el:
* test/lisp/emacs-lisp/bytecomp-tests.el
(bytecomp-tests--unescaped-char-literals)
(bytecomp-tests-function-put, bytecomp-tests--not-writable-directory)
(bytecomp-tests--target-file-no-directory):
Update tests.
(bytecomp-tests--log-from-compilation)
(bytecomp-tests--lexical-binding-cookie): New test.

The functions make-process and make-network-process have many
keyword args and it's easy to misspell some of them.

Use a compiler macro to warn about some possible mistakes.

* lisp/emacs-lisp/bytecomp.el (bytecomp--check-keyword-args): New
  helper.
  (make-process, make-network-process): Define a compiler macro that
  performs some checks but doesn't anything else.

* test/lisp/emacs-lisp/bytecomp-tests.el: Add some tests.

* test/lisp/emacs-lisp/bytecomp-resources/:
  (warn-make-process-missing-keyword-arg.el,
   warn-make-process-missing-keyword-value.el,
   warn-make-process-repeated-keyword-arg.el,
   warn-make-process-unknown-keyword-arg.el): New test files

Only perform the rewrite

   (set 'VAR X) -> (setq VAR X)

for dynamic variables, as `set` isn't supposed to affect
lexical vars (and never does so when interpreted).

* lisp/emacs-lisp/byte-opt.el (byte-optimize-set):
* test/lisp/emacs-lisp/bytecomp-tests.el (bytecomp-tests--xx): New.
(bytecomp-tests--test-cases): Add test cases.
* test/lisp/emacs-lisp/bytecomp-resources/warn-variable-set-nonvariable.el:
Remove obsolete test.

* test/lisp/emacs-lisp/bytecomp-tests.el
("warn-wide-docstring-ignore-function-signature.el"): New test.
* lisp/emacs-lisp/bytecomp.el (byte-compile--wide-docstring-p):
Make regexp more allowing to silence warning.
* test/lisp/emacs-lisp/bytecomp-resources/warn-wide-docstring-ignore-function-signature.el:
New file.

* lisp/emacs-lisp/bytecomp.el (byte-compile-file): Document behavior
if 'no-byte-compile' is set.
* test/lisp/emacs-lisp/bytecomp-tests.el
(byte-compile-file/no-byte-compile): New unit test.
* test/lisp/emacs-lisp/bytecomp-resources/no-byte-compile.el: New test
file.

Doc strings, `declare` and `interactive` forms must appear in that
order and at most once each.  Complain if they don't, instead of
silently ignoring the problem (bug#55905).

* lisp/emacs-lisp/byte-run.el (byte-run--parse-body)
(byte-run--parse-declarations): New.
(defmacro, defun): Check for declaration well-formedness as
described above.  Clarify doc strings.  Refactor some common code.
* test/lisp/emacs-lisp/bytecomp-resources/fun-attr-warn.el:
* test/lisp/emacs-lisp/bytecomp-tests.el (bytecomp-fun-attr-warn):
New test.

Early normalisation of setq during macroexpand-all allows later
stages, cconv, byte-opt and codegen, to be simplified and duplicated
checks to be eliminated.

* lisp/emacs-lisp/macroexp.el (macroexp--expand-all):
Normalise all setq forms to a sequence of (setq VAR EXPR).
Emit warnings if necessary.
* lisp/emacs-lisp/cconv.el (cconv-convert, cconv-analyze-form):
* lisp/emacs-lisp/byte-opt.el (byte-optimize-form-code-walker):
* lisp/emacs-lisp/bytecomp.el (byte-compile-setq):
Simplify.
* test/lisp/emacs-lisp/bytecomp-tests.el: Adapt and add tests.
* test/lisp/emacs-lisp/bytecomp-resources/warn-variable-setq-nonvariable.el;
* test/lisp/emacs-lisp/bytecomp-resources/warn-variable-setq-odd.el:
New files.

* lisp/emacs-lisp/bytecomp.el (byte-compile--wide-docstring-p):
Ignore literal key sequence substitutions.
* test/lisp/emacs-lisp/bytecomp-resources/warn-wide-docstring-ignore-substitutions.el:
New file.
* test/lisp/emacs-lisp/bytecomp-tests.el
("warn-wide-docstring-ignore-substitutions.el"): New test.

Wrong number of arguments in inlining function calls (to `defsubst` or
explicitly using `inline`) did not result in warnings, or in very
cryptic ones.

* lisp/emacs-lisp/byte-opt.el (byte-compile-inline-expand): Add calls
to `byte-compile--check-arity-bytecode`.
* lisp/emacs-lisp/bytecomp.el (byte-compile-emit-callargs-warn)
(byte-compile--check-arity-bytecode): New functions.
(byte-compile-callargs-warn): Use factored-out function.
* test/lisp/emacs-lisp/bytecomp-resources/warn-callargs-defsubst.el:
* test/lisp/emacs-lisp/bytecomp-tests.el ("warn-callargs-defsubst.el"):
New test case.