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