Document more internal functions, macros and constants

[albinahlback]

Mostly used by developers, so I guess it's not a high priority issue. However, it is nice to have a quick glance at it while developing so one can quickly see all the caveats.

For example _arf_demote and the macro nn_mul_2x2. Also arf_mul_rnd_down, and what is the int it is supposed to return?

Edit: I edited the title as I planning to devote a couple of hours to proof read the documents as well as documenting more internal functions.

[fredrik-johansson]

It is also now used by Wolfram Mathematica. Ha. https://youtu.be/_BBdeaqaHVU

Thanks, that's a nice presentation (though off topic for this issue).

Back to the topic: I agree it would be nice to document all these internal functions and macros.

arf_mul_rnd_down returns an inexactness flag, like most other arf functions.

[albinahlback]

@fredrik-johansson, what do you think about a creating generic header for Arb, like FLINT has flint.h? I know arb.h is already taken, but I have two reasons why I think creating such a header is a good idea:

• Including any header of Arb should ship the version of it. Even if you include arf.h, which has a lot of perfectly good end-user functions, you do not get ARB_VERSION.
• When internal things gets documented, the documentation will have a better layout; It simply makes more sense to have LIMB_ONE in documentation for a generic header than under mag.h.

Maybe I'll come up with more reasons later.

Edit: Perhaps arblib.h is a suiting name, although that could be interpreted as a header including everything in the library. Perhaps arb_defs.h is the best variant.