Subject: bug#44677: closed (Re: bug#44677: [PATCH] Various doc fixes for comp.el and comp.c)

From: [email-masked] (GNU bug Tracking System)
Date: Mon, 16 Nov 2020 15:10:01 +0000

Your bug report

#44677: [PATCH] Various doc fixes for comp.el and comp.c

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
44677: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=44677
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#44677: [PATCH] Various doc fixes for comp.el and comp.c
From: Stefan Kangas <[email-masked]>
To: Andrea Corallo <[email-masked]>
Cc: [email-masked]
Date: Mon, 16 Nov 2020 07:09:48 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi Andrea,

Andrea Corallo <[email-masked]> writes:

> thanks for looking into this, indeed this is greatly appreciated.

Happy to help.

> Feel free to push it.

Done.

Subject: [PATCH] Various doc fixes for comp.el and comp.c
From: Stefan Kangas <[email-masked]>
To: [email-masked]
Date: Sun, 15 Nov 2020 18:59:08 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

Severity: wishlist

Please find attached a patch fixing some places in the nativecomp branch
where the docstrings did not follow our conventions.
From 693c9897860f124953b25ece58b1687d36676b21 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <[email-masked]>
Date: Mon, 16 Nov 2020 03:50:10 +0100
Subject: [PATCH] Various doc fixes for comp.el and comp.c

* lisp/emacs-lisp/comp.el: Remove redundant :group args.
(comp-async-cu-done-hook, comp-async-all-done-hook)
(comp-async-env-modifier-form, comp-dry-run)
(comp-ensure-native-compiler, comp-func-ret-typeset)
(comp-func-ret-range, comp-limple-lock-keywords)
(comp-make-curr-block):
* src/comp.c (Fcomp_el_to_eln_filename, Fcomp__init_ctxt)
(Fcomp_native_driver_options_effective_p)
(Fcomp__compile_ctxt_to_file, Fcomp_libgccjit_version)
(Fcomp__register_lambda, Fcomp__register_subr)
(Fcomp__late_register_subr, Fnative_elisp_load, syms_of_comp): Doc fixes.
---
 lisp/emacs-lisp/comp.el | 59 +++++++++++++++++------------------------
 src/comp.c              | 50 +++++++++++++++++-----------------
 2 files changed, 48 insertions(+), 61 deletions(-)

diff --git a/lisp/emacs-lisp/comp.el b/lisp/emacs-lisp/comp.el
index 217eec1b56..8dfe382f76 100644
--- a/lisp/emacs-lisp/comp.el
+++ b/lisp/emacs-lisp/comp.el
@@ -23,6 +23,7 @@
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
+
 ;; This code is an attempt to make the pig fly.
 ;; Or, to put it another way to make a 911 out of a turbocharged VW Bug.
 
@@ -73,27 +74,23 @@ comp-verbose
 - 1 final limple is logged.
 - 2 LAP and final limple and some pass info are logged.
 - 3 max verbosity."
-  :type 'number
-  :group 'comp)
+  :type 'number)
 
 (defcustom comp-always-compile nil
   "Unconditionally (re-)compile all files."
-  :type 'boolean
-  :group 'comp)
+  :type 'boolean)
 
 (defcustom comp-deferred-compilation-black-list
   '()
   "List of regexps to exclude files from deferred native compilation.
 Skip if any is matching."
-  :type 'list
-  :group 'comp)
+  :type 'list)
 
 (defcustom comp-bootstrap-black-list
   '()
   "List of regexps to exclude files from native compilation during bootstrap.
 Skip if any is matching."
-  :type 'list
-  :group 'comp)
+  :type 'list)
 
 (defcustom comp-never-optimize-functions
   '(;; The following two are mandatory for Emacs to be working
@@ -101,39 +98,33 @@ comp-never-optimize-functions
     ;; REMOVE.
     macroexpand rename-buffer)
   "Primitive functions for which we do not perform trampoline optimization."
-  :type 'list
-  :group 'comp)
+  :type 'list)
 
 (defcustom comp-async-jobs-number 0
   "Default number of processes used for async compilation.
 When zero use half of the CPUs or at least one."
-  :type 'number
-  :group 'comp)
+  :type 'number)
 
+;; FIXME: This an abnormal hook, and should be renamed to something
+;; like `comp-async-cu-done-function'.
 (defcustom comp-async-cu-done-hook nil
-  "This hook is run whenever an asyncronous native compilation
-finishes compiling a single compilation unit.
+  "Hook run after asynchronously compiling a single compilation unit.
 The argument FILE passed to the function is the filename used as
 compilation input."
-  :type 'hook
-  :group 'comp)
+  :type 'hook)
 
 (defcustom comp-async-all-done-hook nil
-  "This hook is run whenever the asyncronous native compilation
-finishes compiling all input files."
-  :type 'hook
-  :group 'comp)
+  "Hook run after asynchronously compiling all input files."
+  :type 'hook)
 
 (defcustom comp-async-env-modifier-form nil
-  "Form to be evaluated by each asyncronous compilation worker
-before compilation.  Usable to modify the compiler environment."
-  :type 'list
-  :group 'comp)
+  "Form evaluated before compilation by each asyncronous compilation worker.
+Usable to modify the compiler environment."
+  :type 'list)
 
 (defcustom comp-async-report-warnings-errors t
   "Report warnings and errors from native asynchronous compilation."
-  :type 'boolean
-  :group 'comp)
+  :type 'boolean)
 
 (defcustom comp-native-driver-options nil
   "Options passed verbatim to the native compiler's backend driver.
@@ -142,11 +133,10 @@ comp-native-driver-options
 
 Passing these options is only available in libgccjit version 9
 and above."
-  :type 'list
-  :group 'comp)
+  :type 'list)
 
 (defvar comp-dry-run nil
-  "When non-nil run everything but the C back-end.")
+  "If non-nil, run everything but the C back-end.")
 
 (defconst comp-valid-source-re (rx ".el" (? ".gz") eos)
   "Regexp to match filename of valid input source files.")
@@ -521,7 +511,7 @@ comp-func
 
 (defun comp-ensure-native-compiler ()
   "Make sure Emacs has native compiler support and libgccjit is loadable.
-Raise an error otherwise.
+Signal an error otherwise.
 To be used by all entry points."
   (cond
    ((null (featurep 'nativecomp))
@@ -550,11 +540,11 @@ comp-type-hint-p
   (when (memq func comp-type-hints) t))
 
 (defun comp-func-ret-typeset (func)
-  "Return the typeset returned by function FUNC. "
+  "Return the typeset returned by function FUNC."
   (or (alist-get func comp-known-ret-types) '(t)))
 
 (defsubst comp-func-ret-range (func)
-  "Return the range returned by function FUNC. "
+  "Return the range returned by function FUNC."
   (alist-get func comp-known-ret-ranges))
 
 (defun comp-func-unique-in-cu-p (func)
@@ -607,7 +597,7 @@ comp-limple-lock-keywords
     (,(rx-to-string
        `(seq "(" (group-n 1 (or ,@(mapcar #'symbol-name comp-limple-ops)))))
      (1 font-lock-keyword-face)))
-  "Highlights used by comp-limple-mode.")
+  "Highlights used by `comp-limple-mode'.")
 
 (define-derived-mode comp-limple-mode fundamental-mode "LIMPLE"
   "Syntax-highlight LIMPLE IR."
@@ -1092,8 +1082,7 @@ comp-emit-setimm
 (defun comp-make-curr-block (block-name entry-sp &optional addr)
   "Create a basic block with BLOCK-NAME and set it as current block.
 ENTRY-SP is the sp value when entering.
-The block is added to the current function.
-The block is returned."
+Add block to the current function and return it."
   (let ((bb (make--comp-block-lap addr entry-sp block-name)))
     (setf (comp-limplify-curr-block comp-pass) bb
           (comp-limplify-pc comp-pass) addr
diff --git a/src/comp.c b/src/comp.c
index 0d46428185..2b644dca1b 100644
--- a/src/comp.c
+++ b/src/comp.c
@@ -4031,7 +4031,7 @@ make_directory_wrapper_1 (Lisp_Object ignore)
 
 DEFUN ("comp-el-to-eln-filename", Fcomp_el_to_eln_filename,
        Scomp_el_to_eln_filename, 1, 2, 0,
-       doc: /* Given a source FILENAME return the corresponding .eln filename.
+       doc: /* Return the corresponding .eln filename for source FILENAME.
 If BASE-DIR is nil use the first entry in `comp-eln-load-path'.  */)
   (Lisp_Object filename, Lisp_Object base_dir)
 {
@@ -4173,7 +4173,8 @@ DEFUN ("comp--install-trampoline", Fcomp__install_trampoline,
 
 DEFUN ("comp--init-ctxt", Fcomp__init_ctxt, Scomp__init_ctxt,
        0, 0, 0,
-       doc: /* Initialize the native compiler context. Return t on success.  */)
+       doc: /* Initialize the native compiler context.
+Return t on success.  */)
   (void)
 {
   load_gccjit_if_necessary (true);
@@ -4351,8 +4352,7 @@ DEFUN ("comp-native-driver-options-effective-p",
        Fcomp_native_driver_options_effective_p,
        Scomp_native_driver_options_effective_p,
        0, 0, 0,
-       doc: /* Return t if `comp-native-driver-options' is
-	       effective nil otherwise.  */)
+       doc: /* Return t if `comp-native-driver-options' is effective.  */)
   (void)
 {
 #if defined (LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option)  \
@@ -4398,7 +4398,7 @@ restore_sigmask (void)
 DEFUN ("comp--compile-ctxt-to-file", Fcomp__compile_ctxt_to_file,
        Scomp__compile_ctxt_to_file,
        1, 1, 0,
-       doc: /* Compile as native code the current context to file FILENAME.  */)
+       doc: /* Compile the current context as native code to file FILENAME.  */)
   (Lisp_Object filename)
 {
   load_gccjit_if_necessary (true);
@@ -4492,8 +4492,10 @@ DEFUN ("comp--compile-ctxt-to-file", Fcomp__compile_ctxt_to_file,
 
 DEFUN ("comp-libgccjit-version", Fcomp_libgccjit_version,
        Scomp_libgccjit_version, 0, 0, 0,
-       doc: /* Return the libgccjit version in use in the form
-(MAJOR MINOR PATCHLEVEL) or nil if unknown (pre GCC10).  */)
+       doc: /* Return libgccjit version in use.
+
+The return value has the form (MAJOR MINOR PATCHLEVEL) or nil if
+unknown (before GCC version 10).  */)
   (void)
 {
 #if defined (LIBGCCJIT_HAVE_gcc_jit_version) || defined (WINDOWSNT)
@@ -4975,8 +4977,8 @@ make_subr (Lisp_Object symbol_name, Lisp_Object minarg, Lisp_Object maxarg,
 
 DEFUN ("comp--register-lambda", Fcomp__register_lambda, Scomp__register_lambda,
        7, 7, 0,
-       doc: /* This gets called by top_level_run during load phase to register
-	       anonymous lambdas.  */)
+       doc: /* Register anonymous lambda.
+This gets called by top_level_run during the load phase.  */)
   (Lisp_Object reloc_idx, Lisp_Object minarg, Lisp_Object maxarg,
    Lisp_Object c_name, Lisp_Object doc_idx, Lisp_Object intspec,
    Lisp_Object comp_u)
@@ -5003,8 +5005,8 @@ DEFUN ("comp--register-lambda", Fcomp__register_lambda, Scomp__register_lambda,
 
 DEFUN ("comp--register-subr", Fcomp__register_subr, Scomp__register_subr,
        7, 7, 0,
-       doc: /* This gets called by top_level_run during load phase to register
-	       each exported subr.  */)
+       doc: /* Register exported subr.
+This gets called by top_level_run during the load phase.  */)
   (Lisp_Object name, Lisp_Object minarg, Lisp_Object maxarg,
    Lisp_Object c_name, Lisp_Object doc_idx, Lisp_Object intspec,
    Lisp_Object comp_u)
@@ -5029,8 +5031,8 @@ DEFUN ("comp--register-subr", Fcomp__register_subr, Scomp__register_subr,
 
 DEFUN ("comp--late-register-subr", Fcomp__late_register_subr,
        Scomp__late_register_subr, 7, 7, 0,
-       doc: /* This gets called by late_top_level_run during load
-	       phase to register each exported subr.  */)
+       doc: /* Register exported subr.
+This gets called by late_top_level_run during the load phase.  */)
   (Lisp_Object name, Lisp_Object minarg, Lisp_Object maxarg,
    Lisp_Object c_name, Lisp_Object doc, Lisp_Object intspec,
    Lisp_Object comp_u)
@@ -5057,8 +5059,7 @@ file_in_eln_sys_dir (Lisp_Object filename)
 /* Load related routines.  */
 DEFUN ("native-elisp-load", Fnative_elisp_load, Snative_elisp_load, 1, 2, 0,
        doc: /* Load native elisp code FILENAME.
-	       LATE_LOAD has to be non-nil when loading for deferred
-	       compilation.  */)
+LATE_LOAD has to be non-nil when loading for deferred compilation.  */)
   (Lisp_Object filename, Lisp_Object late_load)
 {
   CHECK_STRING (filename);
@@ -5103,8 +5104,7 @@ DEFUN ("native-elisp-load", Fnative_elisp_load, Snative_elisp_load, 1, 2, 0,
 
 DEFUN ("native-comp-available-p", Fnative_comp_available_p,
        Snative_comp_available_p, 0, 0, 0,
-       doc: /* Returns t if native compilation of Lisp files is available in
-this instance of Emacs, nil otherwise.  */)
+       doc: /* Return non-nil if native compilation support is built-in.  */)
   (void)
 {
 #ifdef HAVE_NATIVE_COMP
@@ -5121,11 +5121,10 @@ syms_of_comp (void)
 #ifdef HAVE_NATIVE_COMP
   /* Compiler control customizes.  */
   DEFVAR_BOOL ("comp-deferred-compilation", comp_deferred_compilation,
-	       doc: /* If non-nil compile asyncronously all .elc files
-being loaded.
+	       doc: /* If non-nil compile loaded .elc files asynchronously.
 
-Once compilation happened each function definition is updated to the
-native compiled one.  */);
+After compilation, each function definition is updated to the native
+compiled one.  */);
   comp_deferred_compilation = true;
 
   DEFSYM (Qcomp_speed, "comp-speed");
@@ -5276,8 +5275,8 @@ syms_of_comp (void)
   Vcomp_native_version_dir = Qnil;
 
   DEFVAR_LISP ("comp-deferred-pending-h", Vcomp_deferred_pending_h,
-	       doc: /* Hash table symbol-name -> function-value.  For
-		       internal use during  */);
+	       doc: /* Hash table symbol-name -> function-value.
+For internal use.  */);
   Vcomp_deferred_pending_h = CALLN (Fmake_hash_table, QCtest, Qeq);
 
   DEFVAR_LISP ("comp-eln-to-el-h", Vcomp_eln_to_el_h,
@@ -5297,9 +5296,8 @@ syms_of_comp (void)
   Vcomp_eln_load_path = Fcons (build_string ("../native-lisp/"), Qnil);
 
   DEFVAR_BOOL ("comp-enable-subr-trampolines", comp_enable_subr_trampolines,
-	       doc: /* When non-nil enable trampoline synthesis
-		       triggerd by `fset' making primitives
-		       redefinable effectivelly.  */);
+	       doc: /* If non-nil, enable trampoline synthesis triggered by `fset'.
+This makes primitives redefinable effectively.  */);
 
   DEFVAR_LISP ("comp-installed-trampolines-h", Vcomp_installed_trampolines_h,
 	       doc: /* Hash table subr-name -> installed trampoline.
-- 
2.29.2