From 14080a1781fe8b55739a8a34b39f0c5ced82680b Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Tue, 30 Jan 2018 21:26:02 -0500 Subject: [PATCH] Update core-packages docstrings; rename doom-module-get => doom-module-flags --- core/core-packages.el | 41 +++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/core/core-packages.el b/core/core-packages.el index 2444b091b..53e6354bf 100644 --- a/core/core-packages.el +++ b/core/core-packages.el @@ -127,8 +127,8 @@ base by `doom!' and for calculating how many packages exist.") ;; (defun doom-initialize (&optional force-p) - "Initialize installed packages (using package.el) and ensure the core packages -are installed. + "Initialize package.el, create all the essential directories, and ensure core +packages are installed. If you byte-compile core/core.el, this function will be avoided to speed up startup." @@ -162,6 +162,8 @@ startup." (setq doom-init-p t)))) (defun doom-initialize-load-path (&optional force-p) + "Populates `load-path', if it hasn't already been. If FORCE-P is non-nil, do +it anyway." (when (or force-p (not doom--package-load-path)) ;; We could let `package-initialize' fill `load-path', but it does more than ;; that alone (like load autoload files). If you want something prematurely @@ -174,7 +176,7 @@ startup." (defun doom-initialize-autoloads () "Ensures that `doom-autoload-file' exists and is loaded. Otherwise run -`doom/reload-autoloads' to generate it." +`doom//reload-autoloads' to generate it. Used from Doom's Makefile." (unless (file-exists-p doom-autoload-file) (quiet! (doom//reload-autoloads)))) @@ -240,20 +242,23 @@ added, if the file exists." if (file-exists-p path) collect path)) -(defun doom-module-get (module submodule) +(defun doom-module-flags (module submodule) "Returns a list of flags provided for MODULE SUBMODULE." (gethash (cons module submodule) doom-modules)) (defun doom-module-enabled-p (module submodule) - "Returns t if MODULE->SUBMODULE is present in `doom-modules'." + "Returns t if MODULE SUBMODULE is enabled (ie. present in `doom-modules')." (and (hash-table-p doom-modules) - (doom-module-get module submodule) + (doom-module-flags module submodule) t)) (defun doom-module-enable (module submodule &optional flags) "Adds MODULE and SUBMODULE to `doom-modules', overwriting it if it exists. -MODULE is a keyword, SUBMODULE is a symbol. e.g. :lang 'emacs-lisp. +MODULE is a keyword, SUBMODULE is a symbol, FLAGS is a list of arbitrary +symbols: + + (doom-module-enable :lang 'haskell '(+intero)) Used by `require!' and `depends-on!'." (let ((key (cons module submodule))) @@ -264,9 +269,7 @@ Used by `require!' and `depends-on!'." doom-modules))) (defun doom-module-pairs () - "Returns `doom-modules' as a list of (MODULE . SUBMODULE) cons cells. The list -is sorted by order of insertion unless ALL-P is non-nil. If ALL-P is non-nil, -include all modules, enabled or otherwise." + "Returns `doom-modules' as a list of (MODULE . SUBMODULE) cons cells." (unless (hash-table-p doom-modules) (error "doom-modules is uninitialized")) (cl-loop for key being the hash-keys of doom-modules @@ -289,7 +292,7 @@ include all modules, enabled or otherwise." (autoload 'use-package "use-package" nil nil 'macro) (defmacro doom! (&rest modules) - "Bootstrap DOOM Emacs. + "Bootstraps DOOM Emacs and its modules. MODULES is an malformed plist of modules to load." (let (init-forms config-forms mode) @@ -406,8 +409,18 @@ The module is only loaded once. If RELOAD-P is non-nil, load it again." (error-message-string ex)))))))) (defmacro featurep! (module &optional submodule flag) - "A convenience macro wrapper for `doom-module-enabled-p'. It is evaluated at -compile-time/macro-expansion time." + "Returns t if MODULE SUBMODULE is enabled. If FLAG is provided, returns t if +MODULE SUBMODULE has FLAG enabled. + + (featurep! :private default) + +Module FLAGs are set in your config's `doom!' block, typically in +~/.emacs.d/init.el. Like so: + + :private (default +flag1 -flag2) + +When this macro is used from inside a module, MODULE and SUBMODULE can be +omitted. eg. (featurep! +flag1)" (unless submodule (let* ((path (or load-file-name byte-compile-current-file)) (module-pair (doom-module-from-path path))) @@ -417,7 +430,7 @@ compile-time/macro-expansion time." module (car module-pair) submodule (cdr module-pair)))) (if flag - (and (memq flag (doom-module-get module submodule)) t) + (and (memq flag (doom-module-flags module submodule)) t) (doom-module-enabled-p module submodule)))