Undocumented exception(s) in the Num module

[vicuna]

Original bug ID: 7065
Reporter: SpiceGuid
Status: acknowledged (set by @gasche on 2015-11-28T20:19:38Z)
Resolution: open
Priority: low
Severity: feature
Target version: later
Category: documentation

Bug description

Some people assume they can compute square root or cubic root by providing
a 1/2 or 1/3 ratio argument to the Num.power_num function.

Unfortunately they can't :

# #load "nums.cma";;
# open Num;;
# int_of_num (Int 27 **/ (Int 1 // Int 3));;
Exception: Invalid_argument "power_num".

The problem is not they can't, the problem is they assume they can and are encouraged by the silent documentation to do so.

I suggest that all Num functions should be totally documented, including exceptions and conditions that can raise them.

[vicuna]

Comment author: @gasche

Patches to propose documentation would be warmly welcome :-)

[nojb]

I guess this should be moved to ocaml/num @xavierleroy

[xavierleroy]

You're right. I derive great pleasure from moving old issues around!

[xavierleroy]

As mentioned earlier, pull requests that propose improvements to the documentation would be warmly welcome.