From 22fb5397defc14c3dbdb48ba7f2f06cb7329be9d Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 5 Nov 2022 13:11:28 +0200 Subject: [PATCH] ; Fix documentation of package-vc.el * lisp/emacs-lisp/package-vc.el (package-vc-default-backend) (package-vc-selected-packages, package-vc--archive-spec-alist) (package-vc--archive-data-alist, package-vc--query-spec) (package-vc--read-archive-data, package-vc-commit) (package-vc--main-file, package-vc--generate-description-file) (package-vc--build-documentation, package-vc--unpack-1) (package-vc--guess-backend, package-vc--clone) (package-vc--unpack, package-vc-update, package-vc--release-rev) (package-vc-install, package-vc-checkout) (package-vc-link-directory, package-vc-refresh) (package-vc-prepare-patch, package-vc--archives-initialize): Doc fixes. --- lisp/emacs-lisp/package-vc.el | 194 +++++++++++++++++----------------- 1 file changed, 99 insertions(+), 95 deletions(-) diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el index aae33096c9e..96cf7bb4666 100644 --- a/lisp/emacs-lisp/package-vc.el +++ b/lisp/emacs-lisp/package-vc.el @@ -109,9 +109,10 @@ (defcustom package-vc-default-backend 'Git "Default VC backend used when cloning a package repository. If no repository type was specified or could be guessed by -`package-vc-heuristic-alist', the VC backend denoted by this -symbol is used. The value must be a member of -`vc-handled-backends' that implements the `clone' function." +`package-vc-heuristic-alist', this is the default VC backend +used as fallback. The value must be a member of +`vc-handled-backends' and the named backend must implement +the `clone' function." :type `(choice ,@(mapcar (lambda (b) (list 'const b)) vc-handled-backends)) :version "29.1") @@ -135,13 +136,12 @@ symbol is used. The value must be a member of ;;;###autoload (defcustom package-vc-selected-packages '() - "List of packages to ensure being installed. -Each entry of the list is of the form (NAME . SPEC), where NAME + "List of packages that must be installed. +Each member of the list is of the form (NAME . SPEC), where NAME is a symbol designating the package and SPEC is one of: -- the value nil, if any package version is to be installed, -- a string, if a specific revision, as designating by the string - is to be installed, +- nil, if any package version can be installed; +- a version string, if that specific revision is to be installed; - a property list of the form described in `package-vc-archive-spec-alist', giving a package specification. @@ -149,7 +149,7 @@ is a symbol designating the package and SPEC is one of: This user option differs from `package-selected-packages' in that it is meant to be specified manually. You can also use the function `package-vc-selected-packages' to apply the changes." - :type '(alist :tag "List of ensured packages" + :type '(alist :tag "List of packages you want to be installed" :key-type (symbol :tag "Package") :value-type (choice (const :tag "Any revision" nil) @@ -166,54 +166,47 @@ function `package-vc-selected-packages' to apply the changes." (defvar package-vc--archive-spec-alist nil "List of package specifications for each archive. -The list maps package names as string to plist. Valid keys -include +The list maps each package name, as a string, to a plist. +Valid keys and the corresponding value types are: - `:url' (string) + `:url' (string) + The URL of the repository used to fetch the package source. -The URL of the repository used to fetch the package source. + `:branch' (string) + If given, the name of the branch to checkout after cloning the directory. - `:branch' (string) + `:lisp-dir' (string) + The repository-relative name of the directory to use for loading the Lisp + sources. If not given, the value defaults to the root directory + of the repository. -If given, the branch to check out after cloning the directory. + `:main-file' (string) + The main file of the project, relevant to gather package metadata. + If not given, the assumed default is the package name with \".el\" + appended to it. - `:lisp-dir' (string) - -The repository-relative directory to use for loading the Lisp -sources. If not given, the value defaults to the root directory -of the repository. - - `:main-file' (string) - -The main file of the project, relevant to gather package -metadata. If not given, the assumed default is the package named -with \".el\" concatenated to the end. - - `:vc-backend' (symbol) - -A symbol indicating what the VC backend to use for cloning a -package. The value ought to be a member of -`vc-handled-backends'. If missing, `vc-clone' will fall back -onto the archive default or `package-vc-default-backend'. + `:vc-backend' (symbol) + A symbol of the VC backend to use for cloning the package. The + value ought to be a member of `vc-handled-backends'. If omitted, + `vc-clone' will fall back onto the archive default or on + `package-vc-default-backend'. All other values are ignored.") (defvar package-vc--archive-data-alist nil - "List of package specification archive metadata. + "List of package specification metadata for archives. Each element of the list has the form (ARCHIVE . PLIST), where PLIST keys are one of: - `:version' (integer) - -Indicating the version of the file formatting, to be compared -with `package-vc--elpa-packages-version'. + `:version' (integer) + Indicates the version of the file formatting, to be compared + with `package-vc--elpa-packages-version'. - `:vc-backend' (symbol) - -A symbol indicating what the default VC backend to use if a -package specification does not indicate anything. The value -ought to be a member of `vc-handled-backends'. If missing, -`vc-clone' will fall back onto `package-vc-default-backend'. + `:vc-backend' (symbol) + A symbol of the default VC backend to use if a package specification + does not indicate a backend. The value ought to be a member of + `vc-handled-backends'. If omitted, `vc-clone' will fall back on + `package-vc-default-backend'. All other values are ignored.") @@ -230,16 +223,15 @@ name for PKG-DESC." nil nil #'string=)) (define-inline package-vc--query-spec (pkg-desc prop) - "Query the property PROP for the package specification for PKG-DESC. + "Query the property PROP for the package specification of PKG-DESC. If no package specification can be determined, the function will return nil." (inline-letevals (pkg-desc prop) (inline-quote (plist-get (package-vc--desc->spec ,pkg-desc) ,prop)))) (defun package-vc--read-archive-data (archive) - "Update `package-vc--archive-spec-alist' with the contents of ARCHIVE. -This function is meant to be used as a hook for -`package--read-archive-hook'." + "Update `package-vc--archive-spec-alist' for ARCHIVE. +This function is meant to be used as a hook for `package--read-archive-hook'." (let ((contents-file (expand-file-name (format "archives/%s/elpa-packages.eld" archive) package-user-dir))) @@ -279,10 +271,10 @@ asynchronously." (add-hook 'package-refresh-contents-hook #'package-vc--download-and-read-archives 20) (defun package-vc-commit (pkg) - "Extract the commit of a development package PKG." + "Return the last commit of a development package PKG." (cl-assert (package-vc-p pkg)) ;; FIXME: vc should be extended to allow querying the commit of a - ;; directory (as is possible when dealing with git repositores). + ;; directory (as is possible when dealing with git repositories). ;; This should be a fallback option. (cl-loop with dir = (package-desc-dir pkg) for file in (directory-files dir t "\\.el\\'" t) @@ -301,7 +293,7 @@ asynchronously." "0")) (defun package-vc--main-file (pkg-desc) - "Return the main file for PKG-DESC." + "Return the name of the main file for PKG-DESC." (cl-assert (package-vc-p pkg-desc)) (let ((pkg-spec (package-vc--desc->spec pkg-desc))) (or (plist-get pkg-spec :main-file) @@ -315,8 +307,7 @@ asynchronously." (plist-get pkg-spec :lisp-dir)))))) (defun package-vc--generate-description-file (pkg-desc pkg-file) - "Generate a package description file for PKG-DESC. -The output is written out into PKG-FILE." + "Generate a package description file for PKG-DESC and write it to PKG-FILE." (let ((name (package-desc-name pkg-desc))) ;; Infer the subject if missing. (unless (package-desc-summary pkg-desc) @@ -360,7 +351,9 @@ The output is written out into PKG-FILE." (declare-function org-export-to-file "ox" (backend file)) (defun package-vc--build-documentation (pkg-desc file) - "Build documentation FILE for PKG-DESC." + "Build documentation FILE for PKG-DESC. +FILE can be an Org file, indicated by its \".org\" extension, +otherwise it's assumed to be an Info file." (let ((pkg-dir (package-desc-dir pkg-desc))) (when (string-match-p "\\.org\\'" file) (require 'ox) @@ -373,7 +366,7 @@ The output is written out into PKG-FILE." file pkg-dir))) (defun package-vc--unpack-1 (pkg-desc pkg-dir) - "Install PKG-DESC that is already located in PKG-DIR." + "Install PKG-DESC that is already checked-out in PKG-DIR." ;; In case the package was installed directly from source, the ;; dependency list wasn't know beforehand, and they might have ;; to be installed explicitly. @@ -443,14 +436,14 @@ The output is written out into PKG-FILE." (defun package-vc--guess-backend (url) "Guess the VC backend for URL. This function will internally query `package-vc-heuristic-alist' -and return nil if no reasonable guess can be made." +and return nil if it cannot reasonably guess." (and url (alist-get url package-vc-heuristic-alist nil nil #'string-match-p))) (defun package-vc--clone (pkg-desc pkg-spec dir rev) - "Clone the source of a package into a directory DIR. -The package is described by a package descriptions PKG-DESC and a -package specification PKG-SPEC." + "Clone the package PKG-DESC whose spec is PKG-SPEC into the directory DIR. +REV specifies a specific revision to checkout. This overrides the `:branch' +attribute in PKG-SPEC." (pcase-let* ((name (package-desc-name pkg-desc)) ((map :url :branch) pkg-spec)) @@ -477,11 +470,10 @@ package specification PKG-SPEC." (defun package-vc--unpack (pkg-desc pkg-spec &optional rev) "Install the package described by PKG-DESC. -PKG-SPEC is a package specification is a property list describing -how to fetch and build the package PKG-DESC. See -`package-vc--archive-spec-alist' for details. The optional argument -REV specifies a specific revision to checkout. This overrides -the `:brach' attribute in PKG-SPEC." +PKG-SPEC is a package specification, a property list describing +how to fetch and build the package. See `package-vc--archive-spec-alist' +for details. The optional argument REV specifies a specific revision to +checkout. This overrides the `:branch' attribute in PKG-SPEC." (pcase-let* (((map :url :lisp-dir) pkg-spec) (name (package-desc-name pkg-desc)) (dirname (package-desc-full-name pkg-desc)) @@ -523,7 +515,7 @@ the `:brach' attribute in PKG-SPEC." package-archive-contents)) (defun package-vc-update (pkg-desc) - "Attempt to update the packager PKG-DESC." + "Attempt to update the package PKG-DESC." ;; HACK: To run `package-vc--unpack-1' after checking out the new ;; revision, we insert a hook into `vc-post-command-functions', and ;; remove it right after it ran. To avoid running the hook multiple @@ -558,13 +550,13 @@ the `:brach' attribute in PKG-SPEC." (vc-pull)))) (defun package-vc--archives-initialize () - "Initialise package.el and fetch package specifications." + "Initialize package.el and fetch package specifications." (package--archives-initialize) (unless package-vc--archive-data-alist (package-vc--download-and-read-archives))) (defun package-vc--release-rev (pkg-desc) - "Find the latest revision that bumps the \"Version\" tag for PKG-DESC. + "Return the latest revision that bumps the \"Version\" tag for PKG-DESC. If no such revision can be found, return nil." (with-current-buffer (find-file-noselect (package-vc--main-file pkg-desc)) (vc-buffer-sync) @@ -586,20 +578,23 @@ If no such revision can be found, return nil." ;;;###autoload (defun package-vc-install (name-or-url &optional name rev backend) - "Fetch the source of NAME-OR-URL. -If NAME-OR-URL is a URL, then the package will be downloaded from -the repository indicated by the URL. The function will try to -guess the name of the package using `file-name-base'. This can -be overridden by manually passing the optional NAME. Otherwise -NAME-OR-URL is taken to be a package name, and the package -metadata will be consulted for the URL. An explicit revision can -be requested using REV. If the command is invoked with a prefix -argument, the revision used for the last release in the package -archive is used. This can also be reproduced by passing the -special value `:last-release' as REV. If a NAME-OR-URL is a URL, -that is to say a string, the VC backend used to clone the -repository can be set by BACKEND. If missing, -`package-vc--guess-backend' will be used." + "Fetch a package NAME-OR-URL and set it up for using with Emacs. +If NAME-OR-URL is a URL, download the package from the repository +at that URL; the function will try to guess the name of the package +from the URL. Otherwise NAME-OR-URL should be a symbol whose name +is the package name, and the URL for the package will be taken from +the package's metadata. +By default, this function installs the last version of the package +available from its repository, but if REV is given and non-nil, it +specifies the revision to install. If REV has the special value +`:last-release' (interactively, the prefix argument), that stands +for the last released version of the package. +When calling from Lisp, optional argument NAME overrides the package +name as deduced from NAME-OR-URL. +Optional argument BACKEND specifies the VC backend to use for cloning +the package's repository; this is only possible if NAME-OR-URL is a URL, +a string. If BACKEND is omitted or nil, the function +uses `package-vc--guess-backend' to guess the backend." (interactive (progn ;; Initialize the package system to get the list of package @@ -637,12 +632,15 @@ repository can be set by BACKEND. If missing, ;;;###autoload (defun package-vc-checkout (pkg-desc directory &optional rev) - "Clone the sources for PKG-DESC into DIRECTORY and open it. -An explicit revision can be requested by passing a string to the -optional argument REV. If the command is invoked with a prefix -argument, the revision used for the last release in the package -archive is used. This can also be reproduced by passing the -special value `:last-release' as REV." + "Clone the sources for PKG-DESC into DIRECTORY and visit that directory. +Unlike `package-vc-install', this does not yet set up the package +for use with Emacs; use `package-vc-link-directory' for setting +the package up after this function finishes. +Optional argument REV means to clone a specific version of the +package; it defaults to the last version available from the +package's repository. If REV has the special value +`:last-release' (interactively, the prefix argument), that stands +for the last released version of the package." (interactive (progn ;; Initialize the package system to get the list of package @@ -668,10 +666,12 @@ special value `:last-release' as REV." ;;;###autoload (defun package-vc-link-directory (dir name) - "Install the package NAME in DIR by linking it into the ELPA directory. -If invoked interactively with a prefix argument, the user will be -prompted for the package NAME. Otherwise it will be inferred -from the base name of DIR." + "Set up the package NAME in DIR by linking it into the ELPA directory. +Interactively, prompt the user for DIR, which should be a directory +under version control, typically one created by `package-vc-checkout'. +If invoked interactively with a prefix argument, prompt the user +for the NAME of the package to set up. Otherwise infer the package +name from the base name of DIR." (interactive (let ((dir (read-directory-name "Directory: "))) (list dir (if current-prefix-arg @@ -690,7 +690,8 @@ from the base name of DIR." ;;;###autoload (defun package-vc-refresh (pkg-desc) - "Refresh the installation for PKG-DESC." + "Refresh the installation for package given by PKG-DESC. +Interactively, prompt for the name of the package to refresh." (interactive (package-vc--read-pkg "Refresh package: ")) (package-vc--unpack-1 pkg-desc (package-desc-dir pkg-desc))) @@ -706,9 +707,12 @@ from the base name of DIR." ;;;###autoload (defun package-vc-prepare-patch (pkg subject revisions) - "Send a patch to the maintainer of a package PKG. -SUBJECT and REVISIONS are used passed on to `vc-prepare-patch'. -PKG must be a package description." + "Send patch for REVISIONS to maintainer of the package PKG using SUBJECT. +SUBJECT and REVISIONS are passed on to `vc-prepare-patch', which see. +PKG must be a package description. +Interactively, prompt for PKG, SUBJECT, and REVISIONS. However, +if the current buffer has marked commit log entries, REVISIONS +are the tags of the marked entries, see `log-view-get-marked'." (interactive (list (package-vc--read-pkg "Package to prepare a patch for: ") (and (not vc-prepare-patches-separately) -- 2.39.2