[issue21510] fma documentation should provide better example.

Raymond Hettinger added the comment: I suggest using the text and example from the spec: http://speleotrove.com/decimal/daops.html#reffma = fused-multiply-add takes three operands; the first two are multiplied together, using multiply, with

[issue21510] fma documentation should provide better example.

Change by Irit Katriel : -- versions: +Python 3.10, Python 3.9 -Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 ___ Python tracker ___

[issue21510] fma documentation should provide better example.

Stefan Krah added the comment: I have no strong opinion, except that the docs appear clear: Return self*other+third with no rounding of the intermediate product self*other. -- ___ Python tracker rep...@bugs.python.org

[issue21510] fma documentation should provide better example.

Antoine Pitrou added the comment: Just for the record, I think that an example also helps educate a non-expert reader (such as me ;-)) about the rounding problem. -- nosy: +pitrou ___ Python tracker rep...@bugs.python.org

[issue21510] fma documentation should provide better example.

Changes by Mark Dickinson dicki...@gmail.com: -- nosy: +mark.dickinson, skrah ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue21510 ___ ___

[issue21510] fma documentation should provide better example.

Mark Dickinson added the comment: I wouldn't want to drop the simple example: I suspect that many of those looking at fma won't have the first idea what it does, and that first example shows clearly that it's a fused multiply-add. But +1 for an example that demonstrates the single rounding,

[issue21510] fma documentation should provide better example.

Jayanth Koushik added the comment: @Mark: I agree. And perhaps it is also worth mentioning (on an unrelated note), that the decimal fma is not based on the internal cmath fma (it could not be) and unlike the cmath fma, it is no faster than an unfused multiply-add. --

[issue21510] fma documentation should provide better example.

New submission from Jayanth Koushik: The documentation for decimal.fma provides an example which fails to illustrate the most important feature of the function i.e. single rounding. In fact: Decimal(2).fma(3, 5) == Decimal(2)*3 + 5 An example such as this would make it much more clear: