Re: native-comp-async-report-warnings-errors default value

[Robert Pluim]

>>>>> On Tue, 07 Dec 2021 16:28:22 +0200, Eli Zaretskii <eliz@gnu.org> said:
    >> Itʼs not in the elisp manual. I think the docstring of
    >> `native-comp-async-report-warnings-errors' is also not discoverable
    >> from the *Warnings* buffer, from what I remember.

    Eli> We can always improve the documentation in this area.  Feel free to
    Eli> propose a patch, or explain what needs to be improved there, so that
    Eli> someone else could do it.

Let the wordsmithing begin!

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 523758c10f..a3557e6855 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -924,7 +924,11 @@ Native-Compilation Functions
 use while the compilation runs in the background.  This is the method
 used by Emacs to natively-compile any Lisp file or byte-compiled Lisp
 file that is loaded into Emacs, when no natively-compiled file for it
-is available.
+is available.  Note that because of this use of a subprocess, native
+compilation may produce warning and errors which byte-compilation does
+not, and lisp code may thus need to be modified to work correctly. See
+@code{native-comp-async-report-warnings-errors} in @xref{Native-Compilation
+Variables} for more details.
 
 @defun native-compile-async files &optional recursively load selector
 This function compiles the named @var{files} asynchronously.  The
@@ -1038,6 +1042,12 @@ Native-Compilation Variables
 @code{t} means display the resulting buffer.  To log warnings without
 popping up the @file{*Warnings*} buffer, set this variable to
 @code{silent}.
+
+  A common cause for asynchronous native-compilation to produce
+warnings is compiling a file that is missing some @code{require} of a
+necessary feature.  The feature may be loaded into the main emacs, but
+because native compilation always starts from a subprocess with a
+pristine environment, that may not be true for the subprocess.
 @end defopt
 
 @defopt native-comp-async-query-on-exit

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 523758c10f..850cdff465 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -924,7 +924,10 @@ Native-Compilation Functions
 use while the compilation runs in the background.  This is the method
 used by Emacs to natively-compile any Lisp file or byte-compiled Lisp
 file that is loaded into Emacs, when no natively-compiled file for it
-is available.
+is available.  Note that because of this use of a subprocess, native
+compilation may produce warning and errors which byte-compilation does
+not, and lisp code may thus need to be modified to work correctly. See
+@code{native-comp-async-report-warnings-errors} for more details.
 
 @defun native-compile-async files &optional recursively load selector
 This function compiles the named @var{files} asynchronously.  The

Regarding discoverability, the
*Warnings* buffer has entries like this:

    Warning (comp): tex-site.el:168:31: Warning: the function
    ‘BibTeX-auto-store’ is not known to be defined. Disable showing
    Disable logging

I guess we could add a link to
`native-comp-async-report-warnings-errors' when the warning type == (comp)

Robert
--