-
Notifications
You must be signed in to change notification settings - Fork 28.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: update os.uptime() and process.uptime() descriptions #12294
Conversation
doc/api/os.md
Outdated
*Note*: Within Node.js' internals, this number is represented as a `double`. | ||
However, fractional seconds are not returned and the value can typically be | ||
treated as an integer. | ||
*Note*: the return value includes fractions of a second on Windows. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would phrase it as:
-*Note*: On Windows (and maybe other platforms as well) the value returned includes fractions of a second.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(and maybe other platforms as well)
The docs are the canonical source for what our API does, we should be exact. I don't think there are any other platforms that do fractions of a second, but if there are, we can update the docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we should be exact.
@gibfahn I agree in principle, can we figure this out exactly? Until recently we had a hard time list all supported platform (#11872). Mentioning Windows has an implicit meaning that it's only on Windows. And as @bnoordhuis said
UNIX implementations of that function don't currently bother to mix in the sub-second fraction. That could change in the future though, if someone requests it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So:
-*Note*: The value returned may include fractions of a second (on Windows it consistently does, on others it's not defined).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I checked macOS, Ubuntu 16.04, SmartOS 16, FreeBSD 11, and AIX 6.1, and they're all consistent (os.uptime()
is an integer, process.uptime()
is not). Given that, I'd say we're okay to specify that it's just Windows.
If it changes in the future then the PR to change it should update the docs, making it a semver-major
change.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
-*Note*: The value returned may include fractions of a second (on Windows it consistently returns a float. Other platforms currently returns an integer but may change in the future).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
PR to change it should update the docs, making it a semver-major change.
It might get changed by the OS, under us
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@refack Could you repeat the proposed wording in the main thread? Somebody may not look in the outdated discussion.
maybe add the same to process.md:1669 |
@refack |
@vsemozhetbyt You could just include this bit in
|
Is |
@vsemozhetbyt No. I've rephrased, and would wait for a +1 from some else |
Proposing: |
I have too many lawyer friends... |
I'm pretty sure the UNIX implementations @bnoordhuis is talking about in #12291 (comment) are in libuv, not in the OS itself. So it can only change in a libuv update (which would need to update the docs). EDIT: e.g. here See also libuv/libuv@556fe1a |
Let me look... |
yep, saw it. So phrase: |
Ref: libuv/libuv#1294 |
I've updated according to the last proposition for now. @nodejs/documentation PTAL |
Landed in 9b6376a |
Can someone confirm that that is true for v6.x |
ping @vsemozhetbyt |
@gibfahn It seems this is true for the last v6. Does this land cleanly or should I make a backport PR? |
Lands cleanly |
Checklist
Affected core subsystem(s)
doc, os
Fixes: #12291