doc: Improve C API manual for complex number objects - #156914
Conversation
bedevere-app
Bot
added
docs
Documentation build overview
|
| this function returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`. | ||
|
|
||
| Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows. | ||
| On overflow, this function sets :c:data:`errno` to :c:macro:`!ERANGE`. |
There was a problem hiding this comment.
I don't think that old sentence was wrong or grammatically invalid. Lets keep it as is.
There was a problem hiding this comment.
The old sentence is imperative. It's giving an order to the reader to do something. But, it's not intended for the reader to set anything. It's the function that sets errno. The sentence above is already correct. The mismatch between the two is jarring to a native English speaker. Let's make the change.
There was a problem hiding this comment.
The old sentence is imperative. It's giving an order to the reader to do something.
Ok, up to other reviewers. This still looks as a code churn for me.
And, perhaps, this open a Pandora box... Look on PyLong_AsInt64():
Set *value and return 0 on success. Set an exception and return -1 on error.
| Return the absolute value of the complex number *num*. | ||
|
|
||
| Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows. | ||
| On overflow, this function sets :c:data:`errno` to :c:macro:`!ERANGE`. |
| If *exp* is zero, this function returns ``{1.0, 0.0}``; otherwise | ||
| if *num* is zero and *exp* is not a positive real number, | ||
| this function returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`. |
There was a problem hiding this comment.
| If *exp* is zero, this function returns ``{1.0, 0.0}``; otherwise | |
| if *num* is zero and *exp* is not a positive real number, | |
| this function returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`. | |
| If *num* is zero and *exp* is not a nonnegative real number, | |
| this function returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`. |
There was a problem hiding this comment.
I think it's good to document the return value in this case because I do not think it's documented in the C standard. MPC, Python, GNU libc, Intel libm, FreeBSD-15 all do as I've written in this PR. (Older versions of FreeBSD did not, but it was changed when my colleague reported it to them.) I think AMD's libm returns (0, 0).
Numeric Types footnote 5 states:
Python defines
pow(0, 0)and0 ** 0to be1, as is common for programming languages.
It's not something we'd want to change in the future.
The phrase "not nonnegative" is awkward. I prefer my wording.
There was a problem hiding this comment.
I do not think it's documented in the C standard.
Then perhaps it's a good reason to not document this?
We also have a lot of other corner cases for complex numbers with special components: #60200 (comment)
But anyway, we don't develop deprecated stuff, that includes soft-deprecated API like _Py_c_pow().
The phrase "not nonnegative" is awkward.
Well, then up to other reviewers. It's precise, there is no double negation, if you are about.
|
|
||
| If *num* is null and *exp* is not a positive real number, | ||
| this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`. | ||
| If *exp* is zero, this function returns ``{1.0, 0.0}``; otherwise |
There was a problem hiding this comment.
Do you prefer the following suggestion?
| If *exp* is zero, this function returns ``{1.0, 0.0}``; otherwise | |
| If *num* is zero and *exp* is zero, this function returns ``{1.0, 0.0}``; otherwise |
2 participants
The actual change is to note that
The other minor wording changes, I believe, increase consistency. Feel free to change it if you feel otherwise.
CC: @skirpichev @eendebakpt @serhiy-storchaka