[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: documentation incorrect for function `define-package'?
From: |
Stefan Kangas |
Subject: |
Re: documentation incorrect for function `define-package'? |
Date: |
Fri, 24 Sep 2021 08:01:14 -0700 |
Michelangelo Rodriguez <michelangelo.rodriguez@gmail.com> writes:
> The documentation for `define-package' function says:
> EXTRA-PROPERTIES is currently unused.
> But, indeed, it's not true.
> In order for a multi-package to correctly work, and in particular to
> `describe-package' to report correctly information on a multi-package,
> it is necessary to specify keywords as :author, :keywords, and so on...
> Neither function documentation nor info manual mention that.
> Infact, if i specify only library headers containing that information,
> describe-package don't report keywords, nor other tags.
This is its current definition:
(defun define-package ( _name-string _version-string
&optional _docstring _requirements
&rest _extra-properties)
"Define a new package.
NAME-STRING is the name of the package, as a string.
VERSION-STRING is the version of the package, as a string.
DOCSTRING is a short description of the package, a string.
REQUIREMENTS is a list of dependencies on other packages.
Each requirement is of the form (OTHER-PACKAGE OTHER-VERSION),
where OTHER-VERSION is a string.
EXTRA-PROPERTIES is currently unused."
;; FIXME: Placeholder! Should we keep it?
(error "Don't call me!"))
On the one hand, this function is clearly not intended for use.
On the other hand, where else do we document the `define-package' list
that goes in "foo-pkg.el"?
Those definitions look like this, but again this is just data (the
"package.el" Commentary section incorrectly says "'PACKAGE-pkg.el' which
consists of a *call* to define-package", my emphasis):
(define-package "which-key" "20210824.11" "Display available
keybindings in popup" '((emacs "24.4")) :commit
"4790a14683a2f3e4f72ade197c78e4c0af1cdd4b" :authors '(("Justin
Burkett" . "justin@burkett.cc")) :maintainer '("Justin Burkett" .
"justin@burkett.cc") :url
"https://github.com/justbur/emacs-which-key")