pkg-autoloads.el vs. pkg-loaddefs.el

[Ihor Radchenko <yantar92@posteo.net>]

Hello,

According to 43.1 Packaging Basics section of Elisp manual, package
autoloads are saved into pkg-autoloads.el file.

However, on master, there is also `generated-autoload-file' variable
that can override the file name where to write the autoloads. So,
pkg-autoloads.el is not always the file where autoloads are written.

Further, `elpaa-batch-generate-autoloads' in ELPA/admin/elpa-admin.el
hard-codes pkg-autoloads.el. And I got a report that in some Emacs
packages distributed through ELPA (org-mode, tramp, hyperbole), both
pkg-autoloads and pkg-loaddefs are generated.

Finally, all the libraries in Emacs core are using name-loaddefs.el.

I feel confused about where to use which name. There is apparent
inconsistency in the above facts.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>