[R] Expand documentation for decimal()

[asfimport]

Two main things we could update here:

1. The general description of what the decimal type is and is for and/or a link to the C++ docs - in the details section, add some explanation of what an Arrow decimal() type is and why it is automatically mapped to an R double type

2. Documentation of the params precision and scale.  We could add a bit more information to explain what that actually means to the user, as it's not immediately obvious.

    

Reporter: Nicola Crane / @thisisnic
Assignee: Dragoș Moldovan-Grünfeld / @dragosmg

Related issues:

• [C++] Improve precision range error messages for Decimal128Type/Decimal256Type (relates to)
• [R] Implement decimal128() (to replace decimal()) (relates to)
• [R] Implement decimal256() (relates to)

PRs and other links:

• GitHub Pull Request #11758

_{Note: This issue was originally created as ARROW-13886. Please see the migration documentation for further details.}

[asfimport]

Dragoș Moldovan-Grünfeld / @dragosmg:
We implement the R decimal() as a binding to {}Decimal128Type{}. This means that the maximum precision it can deal with is 38 significant digits. I think we should implement a check on precision <= 38 and offer an informative message. 

[asfimport]

Neal Richardson / @nealrichardson:
See also ARROW-4621 and ARROW-11631

[asfimport]

Dragoș Moldovan-Grünfeld / @dragosmg:
I think ARROW-4621 might already be solved by these tests. Or do we need to expand them?

[asfimport]

Neal Richardson / @nealrichardson:
That's just the type. I believe there still aren't tests for working with Decimal arrays. Though the example on ARROW-11631 suggests that you could write tests by creating floats and casting to decimal, so that's something.

[asfimport]

Dragoș Moldovan-Grünfeld / @dragosmg:
Should we extend the ticket to deprecate decimal() and implement decimal128() and decimal256() as per Antoine's suggestion:

"For the record, it would be good to deprecate the decimal call and replace it with decimal128 (also, is decimal256 exposed?)."

Any thoughts? @thisisnic @nealrichardson @jonkeane @paleolimbot

[asfimport]

Neal Richardson / @nealrichardson:
Probably so, IIUC that would be more consistent with the C++ library and others.

[asfimport]

Dragoș Moldovan-Grünfeld / @dragosmg:
I think I will address the issue as-is in this ticket and then open follow-up tickets to implement decimal128() a direct replacement for decimal() and decimal256() - which is a bit more involved.

[asfimport]

Nicola Crane / @thisisnic:
Issue resolved by pull request 11758
#11758