[HELP] Please help checking function definitions in the manual vs. docstrings (was: [BUG] Typo in manual [9.5.2 (9.5.2-gfbff08 @ /home/ignacio/.emacs.d/elpa/org-9.5.2/)])

[Ihor Radchenko <yantar92@gmail.com>]

Marco Wahl <marcowahlsoft@gmail.com> writes:

> Ignacio Casso <ignaciocasso@hotmail.com> writes:
>
>> I would like to report a minor typo in the manual, although I'm not sure
>> if this is the right place (please point me to it if it's not).
>
> Confirmed.

I fixed the exact typo on main for now.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=580f2861402ebd9c4effe0c8db5e6efdc139e79a
Fixed.

> And this is the right place to report this bug.  Thanks!
>
>> In the section Appendix A Hacking -> Using the Mapping API
>> (https://orgmode.org/manual/Using-the-Mapping-API.html), it says that
>> org-map-entries returns an alist, but it actually returns a list (as
>> correctly stated by C-h f org-map-entries).
>
> To me this looks like the documentation in the manual started from the
> documentation of the function.  and with time these two documentations
> diverged.
>
> What about removing the (diverged) duplication of the documentation of
> function org-map-entries from the manual?

I do not think that we should remove the function description from the
manual completely. There should be at least some description. Good
enough to get the users started.

Moreover, this function is not the only place where the outdated
docstring is used directly in the manual. Search for #+begin_defun in
the manual and try comparing manual vs. the actual docstring.

We may need to go through these function definitions and strip them out
of excessive details that might be a subject of change. Just leave the
essence about what the function does.

The above is just my suggestion though. Do note that Elisp manual is
using similar approach to the Org manual - a number of functions pretty
much have their docstrings copied from the code to the manual. And they
also do diverge...

I am not sure which way is better.

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