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

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 146 bytes --]

Severity: wishlist

Please find attached a patch fixing some places in the nativecomp branch
where the docstrings did not follow our conventions.

[-- Attachment #2: 0001-Various-doc-fixes-for-comp.el-and-comp.c.patch --]
[-- Type: text/x-diff, Size: 12700 bytes --]

From 693c9897860f124953b25ece58b1687d36676b21 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
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

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

[Andrea Corallo via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Stefan Kangas <stefan@marxist.se> writes:

> Severity: wishlist
>
> Please find attached a patch fixing some places in the nativecomp branch
> where the docstrings did not follow our conventions.

Hi Stefan,

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

Feel free to push it.

  Andrea

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

[Stefan Kangas]

Hi Andrea,

Andrea Corallo <akrl@sdf.org> writes:

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

Happy to help.

> Feel free to push it.

Done.