doc: update os.uptime() and process.uptime() descriptions #12294

vsemozhetbyt · 2017-04-09T19:44:30Z

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc, os

refack · 2017-04-09T20:07:09Z

doc/api/os.md

-*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.


~~I would phrase it as:~~
~~-*Note*: On Windows (and maybe other platforms as well) the value returned includes fractions of a second.~~

(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.

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.

So:
-*Note*: The value returned may include fractions of a second (on Windows it consistently does, on others it's not defined).

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.

-*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).

PR to change it should update the docs, making it a semver-major change.

It might get changed by the OS, under us

@refack Could you repeat the proposed wording in the main thread? Somebody may not look in the outdated discussion.

refack · 2017-04-09T20:11:20Z

maybe add the same to process.md:1669

vsemozhetbyt · 2017-04-09T20:16:10Z

@refack process.uptime() doc does not state to return integer and it is the same for all OS, it seems.

gibfahn · 2017-04-09T20:17:58Z

maybe add the same to process.md:1669

@vsemozhetbyt You could just include this bit in process.md:

Note: the return value includes fractions of a second. Use Math.floor() to get whole seconds.

vsemozhetbyt · 2017-04-09T20:27:27Z

Is (and maybe some other platforms as well) OK?

refack · 2017-04-09T20:29:06Z

@vsemozhetbyt No. I've rephrased, and would wait for a +1 from some else
/cc @gibfahn @bnoordhuis

refack · 2017-04-09T20:55:13Z

gibfahn 8 minutes ago • edited Member
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.

refack 5 minutes ago • edited Member
-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).

refack 4 minutes ago Member
PR to change it should update the docs, making it a semver-major change.
It might get changed by the OS, under us

Proposing:
-*Note*: The value returned may include fractions of a second (Windows consistently returns a float. Other platforms currently return a whole number, but may change this behaviour in the future).

refack · 2017-04-09T20:55:45Z

I have too many lawyer friends...

gibfahn · 2017-04-09T20:58:08Z

It might get changed by the OS, under us

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

refack · 2017-04-09T21:19:53Z

are in libuv, not in the OS itself

Let me look...

refack · 2017-04-09T21:27:48Z

are in libuv, not in the OS itself

yep, saw it.

So phrase:
*Note*: On Windows the returned value includes fractions of a second...

refack · 2017-04-09T21:43:51Z

Ref: libuv/libuv#1294

Fixes: #12291

vsemozhetbyt · 2017-04-10T13:28:33Z

I've updated according to the last proposition for now.

@nodejs/documentation PTAL

PR-URL: #12294 Fixes: #12291 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

jasnell · 2017-04-11T09:38:12Z

Landed in 9b6376a

PR-URL: #12294 Fixes: #12291 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

MylesBorins · 2017-05-15T15:51:15Z

Can someone confirm that that is true for v6.x

gibfahn · 2017-06-18T00:14:51Z

Can someone confirm that that is true for v6.x

ping @vsemozhetbyt

vsemozhetbyt · 2017-06-18T00:38:54Z

@gibfahn It seems this is true for the last v6. Does this land cleanly or should I make a backport PR?

PR-URL: #12294 Fixes: #12291 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

gibfahn · 2017-06-18T09:08:21Z

Lands cleanly

PR-URL: #12294 Fixes: #12291 Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

nodejs-github-bot added doc Issues and PRs related to the documentations. os Issues and PRs related to the os subsystem. labels Apr 9, 2017

vsemozhetbyt mentioned this pull request Apr 9, 2017

doc: are os.uptime() returned type and remark correct? #12291

Closed

refack suggested changes Apr 9, 2017

View reviewed changes

vsemozhetbyt changed the title ~~doc: fix os.uptime() description in os.md~~ doc: update os.uptime() and process.uptime() descriptions Apr 10, 2017

doc: update os.uptime() and process.uptime() info

9060613

Fixes: #12291

vsemozhetbyt added libuv Issues and PRs related to the libuv dependency or the uv binding. lts-watch-v4.x windows Issues and PRs related to the Windows platform. labels Apr 10, 2017

refack approved these changes Apr 10, 2017

View reviewed changes

gibfahn approved these changes Apr 10, 2017

View reviewed changes

jasnell approved these changes Apr 11, 2017

View reviewed changes

jasnell closed this Apr 11, 2017

vsemozhetbyt deleted the os-uptime branch April 11, 2017 09:39

evanlucas mentioned this pull request May 1, 2017

v7.10.0 proposal #12775

Merged

MylesBorins removed the lts-watch-v4.x label May 15, 2017

gibfahn mentioned this pull request Jun 15, 2017

Auditing for 6.11.1 nodejs/Release#230

Closed

3 tasks

gibfahn added land-on-v6.x and removed lts-watch-v6.x labels Jun 18, 2017

MylesBorins mentioned this pull request Jul 18, 2017

v6.11.2 proposal #14356

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: update os.uptime() and process.uptime() descriptions #12294

doc: update os.uptime() and process.uptime() descriptions #12294

vsemozhetbyt commented Apr 9, 2017

refack Apr 9, 2017 •

edited

Loading

gibfahn Apr 9, 2017 •

edited

Loading

refack Apr 9, 2017

refack Apr 9, 2017

gibfahn Apr 9, 2017 •

edited

Loading

refack Apr 9, 2017 •

edited

Loading

refack Apr 9, 2017

vsemozhetbyt Apr 9, 2017

refack commented Apr 9, 2017

vsemozhetbyt commented Apr 9, 2017

gibfahn commented Apr 9, 2017 •

edited

Loading

vsemozhetbyt commented Apr 9, 2017

refack commented Apr 9, 2017

refack commented Apr 9, 2017

refack commented Apr 9, 2017

gibfahn commented Apr 9, 2017 •

edited

Loading

refack commented Apr 9, 2017

refack commented Apr 9, 2017

refack commented Apr 9, 2017

vsemozhetbyt commented Apr 10, 2017

jasnell commented Apr 11, 2017

MylesBorins commented May 15, 2017

gibfahn commented Jun 18, 2017

vsemozhetbyt commented Jun 18, 2017

gibfahn commented Jun 18, 2017

doc: update os.uptime() and process.uptime() descriptions #12294

doc: update os.uptime() and process.uptime() descriptions #12294

Conversation

vsemozhetbyt commented Apr 9, 2017

Checklist

Affected core subsystem(s)

refack Apr 9, 2017 • edited Loading

Choose a reason for hiding this comment

gibfahn Apr 9, 2017 • edited Loading

Choose a reason for hiding this comment

refack Apr 9, 2017

Choose a reason for hiding this comment

refack Apr 9, 2017

Choose a reason for hiding this comment

gibfahn Apr 9, 2017 • edited Loading

Choose a reason for hiding this comment

refack Apr 9, 2017 • edited Loading

Choose a reason for hiding this comment

refack Apr 9, 2017

Choose a reason for hiding this comment

vsemozhetbyt Apr 9, 2017

Choose a reason for hiding this comment

refack commented Apr 9, 2017

vsemozhetbyt commented Apr 9, 2017

gibfahn commented Apr 9, 2017 • edited Loading

vsemozhetbyt commented Apr 9, 2017

refack commented Apr 9, 2017

refack commented Apr 9, 2017

refack commented Apr 9, 2017

gibfahn commented Apr 9, 2017 • edited Loading

refack commented Apr 9, 2017

refack commented Apr 9, 2017

refack commented Apr 9, 2017

vsemozhetbyt commented Apr 10, 2017

jasnell commented Apr 11, 2017

MylesBorins commented May 15, 2017

gibfahn commented Jun 18, 2017

vsemozhetbyt commented Jun 18, 2017

gibfahn commented Jun 18, 2017

refack Apr 9, 2017 •

edited

Loading

gibfahn Apr 9, 2017 •

edited

Loading

gibfahn Apr 9, 2017 •

edited

Loading

refack Apr 9, 2017 •

edited

Loading

gibfahn commented Apr 9, 2017 •

edited

Loading

gibfahn commented Apr 9, 2017 •

edited

Loading