Re: as for Calc and the math library

[Eli Zaretskii <eliz@gnu.org>]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: incal@dataswamp.org, emacs-devel@gnu.org
> Date: Sun, 11 Aug 2024 18:27:16 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> 1. Documenting some Calc data structures
> >> 2. Possibly refactoring some Calc functions to use simpler API.
> >> 
> >> It would be a much easier task and can improve the existing
> >> functionality.
> >
> > I don't think I understand well enough what will this entail in
> > practice.  Can you show an example of doing this for a couple of
> > functions?
> 
> For (1), I was referring to ";;;; Arithmetic routines." in
> calc.el.

(1) is documentation of Calc data structures.  If you mean the large
commentary that describes the various form of objects that Calc can
handle, then what is left to document?

> Now, people must simply know the internal format of special
> number representations to work with Calc from Elisp.
> It might be worth (a) putting them into a proper manual (some kind of
> Calc Lisp API description); (b) maybe creating constructor functions to
> abstract the types away.

Doesn't (a) already exist in the Calc manual chapter "Data Types"?
And if not, then you are talking about enhancing the documentation of
Calc, which is always welcome, but I fail to see how it is a step
towards a separate library.

> For (2), for starters, Calc functions often do not even have
> docstrings. One simply has to guess(?) or read the code to understand
> what kinds of values can be passed.

And how is this relevant to (2), which is about refactoring some of
Calc code into hopefully easier-to-use functions?

> For example, take `math-add' - no
> docstring, and go try adding invalid arguments:
> 
> M-: (math-add "foo" '(frac 1 2))

It's a small wonder that you cannot math-add a string, especially
since none of the objects described in the commentary are any kind of
string.  More generally, AFAIU these don't have doc strings because
they are internal functions.

But still, I don't understand the relevance.

> but somehow not
> 
> M-: (math-add 0.1 '(frac 1 10))
> 
> Debugger entered--Lisp error: (wrong-type-argument integer-or-marker-p 2.0)
>   (math-gcd 2.0 10)
>   (math-make-frac 2.0 10)
>   (calc-add-fractions 0.1 (frac 1 10))
>   (math-add 0.1 (frac 1 10))

You again play against the rules: 0.1 is not a valid object for these
functions.  Try

  M-: (math-add '(float 1 -1) '(frac 1 10))