gh-101575: document Decimal.__round__()

[OTheDev]

cc @mdickinson

• Issue: gh-101575

[blaisep]

@encukou , is this something we could merge? I noticed that the topic is still absent after https://docs.python.org/3/library/decimal.html#decimal.Decimal.to_integral_value

[encukou]

Thanks for the mention. The issue here is that we don't want people to call d.__round__() directly; rather they should do round(d), as in the examples. The double-underscore method is for defining the behaviour, not using it; the docs are for users.

I'm not sure how this should be best documented; perhaps describe:: as used for set operations.

[encukou]

After talking to a few docs people, I'm pretty sure .. describe:: is the way to document this.

[encukou]

Looking at the rendered output, I saw the describe looks exactly like a method, which might be confusing. I added an introduction line to separate them. Since i had the change locally to test it, I took the liberty to push the suggestion to this PR; I hope you don't mind.

Does this look good?

[picnixz]

Generally, you'd use .. describe with a "legal" expression, e.g., .. describe:: x in S for the set membership where x and S are explained in a subsequent paragraph. In our case, I would suggest using something like:

.. describe:: round(x)
.. describe:: round(x, n)

Using a signature-based description would indeed be more confusing IMO.

[encukou]

Well, it's not less clear that way, so let's go with it?

[OTheDev]

@encukou @picnixz Thanks! Your suggestions/changes LGTM!

[encukou]

Thank you for the fix, @OTheDev!

[miss-islington-app[bot]]

Thanks @OTheDev for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13. 🐍🍒⛏🤖

[miss-islington-app[bot]]

Thanks @OTheDev for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12. 🐍🍒⛏🤖

[bedevere-app[bot]]

GH-120394 is a backport of this pull request to the 3.13 branch.

[bedevere-app[bot]]

GH-120395 is a backport of this pull request to the 3.12 branch.