From: Stefan Kangas Date: Sun, 22 Sep 2019 00:21:54 +0000 (+0200) Subject: More doc fixes in package.el (Bug#37544) X-Git-Tag: emacs-27.0.90~1302 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=93dd959711222cf594051fa397d6a6e324e136fc;p=emacs.git More doc fixes in package.el (Bug#37544) * lisp/emacs-lisp/package.el (package-menu-hide-low-priority) (package-pinned-packages, package-load-descriptor) package-archive-version, package-archive-contents) package--read-archive-file, package-read-archive-contents) (package-unsigned-archives, package-read-all-archive-contents) (package--download-and-read-archives, package-install): * lisp/subr.el (package--description-file): * test/lisp/emacs-lisp/package-tests.el: Doc fixes. --- diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el index ab1fb8b90fc..188f398a56b 100644 --- a/lisp/emacs-lisp/package.el +++ b/lisp/emacs-lisp/package.el @@ -36,7 +36,7 @@ ;; work.) ;; A package is described by its name and version. The distribution -;; format is either a tar file or a single .el file. +;; format is either a tar file or a single .el file. ;; A tar file should be named "NAME-VERSION.tar". The tar file must ;; unpack into a directory named after the package and version: @@ -160,6 +160,7 @@ ;;; Customization options + ;;;###autoload (defcustom package-enable-at-startup t "Whether to make installed packages available when Emacs starts. @@ -239,7 +240,7 @@ This variable has three possible values: t: both criteria are used. This variable has no effect if `package-menu--hide-packages' is -nil, so it can be toggled with \\ \\[package-menu-toggle-hiding]." +nil, so it can be toggled with \\\\[package-menu-toggle-hiding]." :type '(choice (const :tag "Don't hide anything" nil) (const :tag "Hide per package-archive-priorities" archive) @@ -282,8 +283,7 @@ they are ignored (for this package). If ARCHIVE does not contain PACKAGE, the package will be unavailable." :type '(alist :key-type (symbol :tag "Package") :value-type (string :tag "Archive name")) - ;; I don't really see why this is risky... - ;; I suppose it could prevent you receiving updates for a package, + ;; This could prevent you from receiving updates for a package, ;; via an entry (PACKAGE . NON-EXISTING). Which could be an issue ;; if PACKAGE has a known vulnerability that is fixed in newer versions. :risky t @@ -368,7 +368,9 @@ value of variable `package-check-signature'." package-check-signature)) (defcustom package-unsigned-archives nil - "List of archives where we do not check for package signatures." + "List of archives where we do not check for package signatures. +This should be a list of strings matching the names of package +archives in the variable `package-archives'." :type '(repeat (string :tag "Archive name")) :risky t :version "24.4") @@ -403,6 +405,7 @@ synchronously." ;; user) it makes sense to take the package name as a symbol instead, ;; but keep in mind there could be multiple `package-desc's with the ;; same name. + (defvar package--default-summary "No description available.") (cl-defstruct (package-desc @@ -545,9 +548,9 @@ package." (nth 1 keywords) keywords))) -(defun package-desc-priority (p) - "Return the priority of the archive of package-desc object P." - (package-archive-priority (package-desc-archive p))) +(defun package-desc-priority (pkg-desc) + "Return the priority of the archive of package-desc object PKG-DESC." + (package-archive-priority (package-desc-archive pkg-desc))) (cl-defstruct (package--bi-desc (:constructor package-make-builtin (version summary)) @@ -564,6 +567,7 @@ package." ;; command `package-initialize' is also closely related to this ;; section, but it is left for a later section because it also affects ;; other stuff. + (defvar package--builtins nil "Alist of built-in packages. The actual value is initialized by loading the library @@ -591,6 +595,7 @@ loaded and/or activated, customize `package-load-list'.") (put 'package-activated-list 'risky-local-variable t) ;;;; Populating `package-alist'. + ;; The following functions are called on each installed package by ;; `package-load-all-descriptors', which ultimately populates the ;; `package-alist' variable. @@ -622,7 +627,9 @@ If there already exists a package by that name in new-pkg-desc))) (defun package-load-descriptor (pkg-dir) - "Load the description file in directory PKG-DIR." + "Load the package description file in directory PKG-DIR. +Create a new `package-desc' object, add it to `package-alist' and +return it." (let ((pkg-file (expand-file-name (package--description-file pkg-dir) pkg-dir)) (signed-file (concat pkg-dir ".signed"))) @@ -679,6 +686,7 @@ EXTRA-PROPERTIES is currently unused." ;;; Package activation ;; Section for functions used by `package-activate', which see. + (defun package-disabled-p (pkg-name version) "Return whether PKG-NAME at VERSION can be activated. The decision is made according to `package-load-list'. @@ -1167,6 +1175,7 @@ The return result is a `package-desc'." ;;; Communicating with Archives ;; Set of low-level functions for communicating with archives and ;; signature checking. + (defun package--write-file-no-coding (file-name) (let ((buffer-file-coding-system 'no-conversion)) (write-region (point-min) (point-max) file-name nil 'silent))) @@ -1193,6 +1202,8 @@ The return result is a `package-desc'." (declare-function epg-signature-to-string "epg" (signature)) (defun package--display-verify-error (context sig-file) + "Show error details with CONTEXT for failed verification of SIG-FILE. +The details are shown in a new buffer called \"*Error\"." (unless (equal (epg-context-error-output context) "") (with-output-to-temp-buffer "*Error*" (with-current-buffer standard-output @@ -1380,13 +1391,14 @@ else, even if an error is signaled." ;; function `package-read-all-archive-contents' from a cache on disk. ;; The `package-initialize' command is also closely related to this ;; section, but it has its own section. + (defconst package-archive-version 1 - "Version number of the package archive understood by this file. + "Version number of the package archive understood by package.el. Lower version numbers than this will probably be understood as well.") ;; We don't prime the cache since it tends to get out of date. (defvar package-archive-contents nil - "Cache of the contents of the Emacs Lisp Package Archive. + "Cache of the contents of all archives in `package-archives'. This is an alist mapping package names (symbols) to non-empty lists of `package-desc' structures.") (put 'package-archive-contents 'risky-local-variable t) @@ -1482,9 +1494,9 @@ Also, add the originating archive to the `package-desc' structure." (package--append-to-alist pkg-desc package-archive-contents))))) (defun package--read-archive-file (file) - "Re-read archive file FILE, if it exists. -Will return the data from the file, or nil if the file does not exist. -Will throw an error if the archive version is too new." + "Read cached archive FILE data, if it exists. +Return the data from the file, or nil if the file does not exist. +If the archive version is too new, signal an error." (let ((filename (expand-file-name file package-user-dir))) (when (file-exists-p filename) (with-temp-buffer @@ -1497,8 +1509,10 @@ Will throw an error if the archive version is too new." (cdr contents)))))) (defun package-read-archive-contents (archive) - "Re-read archive contents for ARCHIVE. -If successful, set the variable `package-archive-contents'. + "Read cached archive file for ARCHIVE. +If successful, set or update the variable `package-archive-contents'. +ARCHIVE should be a string matching the name of a package archive +in the variable `package-archives'. If the archive version is too new, signal an error." ;; Version 1 of 'archive-contents' is identical to our internal ;; representation. @@ -1516,8 +1530,8 @@ by arbitrary functions to decide whether it is necessary to call it again.") (defun package-read-all-archive-contents () - "Re-read `archive-contents', if it exists. -If successful, set `package-archive-contents'." + "Read cached archive file for all archives in `package-archives'. +If successful, set or update `package-archive-contents'." (setq package-archive-contents nil) (setq package--old-archive-priorities package-archive-priorities) (dolist (archive package-archives) @@ -1586,6 +1600,7 @@ The variable `package-load-list' controls which packages to load." ;;;; Populating `package-archive-contents' from archives ;; This subsection populates the variables listed above from the ;; actual archives, instead of from a local cache. + (defvar package--downloads-in-progress nil "List of in-progress asynchronous downloads.") @@ -1666,8 +1681,10 @@ similar to an entry in `package-alist'. Save the cached copy to (defun package--download-and-read-archives (&optional async) "Download descriptions of all `package-archives' and read them. -This populates `package-archive-contents'. If ASYNC is non-nil, -perform the downloads asynchronously." +Populate `package-archive-contents' with the result. + +If optional argument ASYNC is non-nil, perform the downloads +asynchronously." ;; The downloaded archive contents will be read as part of ;; `package--update-downloads-in-progress'. (dolist (archive package-archives) @@ -1705,6 +1722,7 @@ downloads in the background." ;; keeping track of which packages were installed strictly as ;; dependencies, and determining which packages cannot be removed ;; because they are dependencies. + (defun package-compute-transaction (packages requirements &optional seen) "Return a list of packages to be installed, including PACKAGES. PACKAGES should be a list of `package-desc'. @@ -2015,12 +2033,17 @@ using `package-compute-transaction'." ;;;###autoload (defun package-install (pkg &optional dont-select) "Install the package PKG. -PKG can be a `package-desc' or a symbol naming one of the available packages -in an archive in `package-archives'. Interactively, prompt for its name. +PKG can be a `package-desc' or a symbol naming one of the +available packages in an archive in `package-archives'. When +called interactively, prompt for the package name. -If called interactively or if DONT-SELECT nil, add PKG to +Mark the installed package as selected by adding it to `package-selected-packages'. +When called from Lisp and optional argument DONT-SELECT is +non-nil, install the package but do not add it to +`package-select-packages'. + If PKG is a `package-desc' and it is already installed, don't try to install it but still mark it as selected." (interactive @@ -2151,6 +2174,7 @@ If some packages are not installed propose to install them." ;;; Package Deletion + (defun package--newest-p (pkg) "Return non-nil if PKG is the newest package with its name." (equal (cadr (assq (package-desc-name pkg) package-alist)) @@ -3026,6 +3050,7 @@ Return (PKG-DESC [NAME VERSION STATUS DOC])." ;;; Package menu faces + (defface package-name '((t :inherit link)) "Face used on package names in the package menu." @@ -3094,6 +3119,7 @@ Return (PKG-DESC [NAME VERSION STATUS DOC])." ;;; Package menu printing + (defun package-menu--print-info-simple (pkg) "Return a package entry suitable for `tabulated-list-entries'. PKG is a `package-desc' object. diff --git a/lisp/subr.el b/lisp/subr.el index da619fef147..fcfc396d140 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -5520,6 +5520,7 @@ NAME is the package name as a symbol, and VERSION is its version as a list.") (defun package--description-file (dir) + "Return package description file name for package DIR." (concat (let ((subdir (file-name-nondirectory (directory-file-name dir)))) (if (string-match "\\([^.].*?\\)-\\([0-9]+\\(?:[.][0-9]+\\|\\(?:pre\\|beta\\|alpha\\)[0-9]+\\)*\\)" subdir) diff --git a/test/lisp/emacs-lisp/package-tests.el b/test/lisp/emacs-lisp/package-tests.el index c757bccf672..f450fd27c28 100644 --- a/test/lisp/emacs-lisp/package-tests.el +++ b/test/lisp/emacs-lisp/package-tests.el @@ -28,7 +28,12 @@ ;; Run this in a clean Emacs session using: ;; -;; $ emacs -Q --batch -L . -l package-test.el -l ert -f ert-run-tests-batch-and-exit +;; $ emacs -Q --batch -L . -l package-tests.el -l ert -f ert-run-tests-batch-and-exit +;; +;; From the top level directory of the Emacs development repository, +;; you can use this instead: +;; +;; $ make -C test package-tests ;;; Code: