Re: documentation incorrect for function `define-package'?

[Stefan Kangas <stefankangas@gmail.com>]

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")