FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: add timeout.close by galkin · Pull Request #40036 · nodejs/node · GitHub

/ node Public

doc: add timeout.close - #40036

Closed
galkin wants to merge 1 commit into
nodejs:masterfrom
galkin:master
ConversationCommits (1)ChecksFiles changed
Closed

doc: add timeout.close#40036
galkin wants to merge 1 commit into
nodejs:masterfrom
galkin:master

Conversation

galkin commented Sep 8, 2021 •
edited
Loading

Copy link
Copy Markdown
Contributor

Hello,

I noticed that the Timeout.close is not documented. We have this method from v0.9.1:

node/lib/timers.js

Lines 274 to 282 in 985e3a2

Timeout.prototype.close = function() {
this._onTimeout = null;
if (this._handle) {
this._handle.ontimeout = null;
this._handle.close();
} else {
exports.unenroll(this);
}
};

Current codebase wraps clearTimeout:

node/lib/timers.js

Lines 251 to 254 in c4096a3

Timeout.prototype.close = function() {
clearTimeout(this);
return this;
};

This pull adds documentation for this method.

nodejs-github-bot added doc Issues and PRs related to the documentations. timers Issues and PRs related to the timers subsystem / setImmediate, setInterval, setTimeout. labels Sep 8, 2021
aduh95 reviewed Sep 8, 2021
View reviewed changes

aduh95 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Thanks for opening this!

Comment thread doc/api/timers.md Outdated
Comment thread doc/api/timers.md Outdated

tniessen commented Sep 8, 2021

Copy link
Copy Markdown
Member

Does this have any benefit over clearTimeout, which is also available in other JS environments?

galkin commented Sep 8, 2021

Copy link
Copy Markdown
Contributor Author

Does this have any benefit over clearTimeout, which is also available in other JS environments?

this is a wrapper around clearTimeout. The name doesn't have _, so there are three options remove right now, document as stable or document as legacy and remove later.

aduh95 commented Sep 8, 2021 •
edited
Loading

Copy link
Copy Markdown
Contributor

document as legacy and remove later.

Actually the legacy status is there for features that we likely won't remove ever:

node/doc/api/documentation.md

Lines 42 to 44 in 6fdd582

> Stability: 3 - Legacy. The feature is no longer recommended for use. While it
> likely will not be removed, and is still covered by semantic-versioning
> guarantees, use of the feature should be avoided.

According to the collaborator guide, if it's a feature that was exposed and we have good reasons to think it's used out there (in this case we know for sure it is), we should document it as public:

node/doc/guides/collaborator-guide.md

Lines 313 to 317 in 7dbc0f7

All functionality in the official Node.js documentation is part of the public
API. Any undocumented object, property, method, argument, behavior, or event is
internal. There are exceptions to this rule. Node.js users have come to rely on
some undocumented behaviors. Collaborators treat many of those undocumented
behaviors as public.

Since it's almost an alias, I think the following applies:

node/doc/guides/collaborator-guide.md

Lines 442 to 443 in 7dbc0f7

Avoid Runtime Deprecations when an alias or a stub/no-op will suffice. An alias
or stub will have lower maintenance costs for end users and Node.js core.

In this case, I personally it should be documented with Legacy status, unless there are use cases where it makes sense to use it over clearTimeout (in which case it should be documented as stable).

galkin requested review from aduh95 and jasnell September 8, 2021 17:37

galkin commented Sep 8, 2021

Copy link
Copy Markdown
Contributor Author

@aduh95, @jasnell, thanks for the explanation. I added Legacy part.

aduh95 approved these changes Sep 8, 2021
View reviewed changes
Comment thread doc/api/timers.md Outdated
aduh95 added the author ready PRs that have at least one approval, no outstanding review comments, and a CI started. label Sep 9, 2021

galkin commented Sep 13, 2021

Copy link
Copy Markdown
Contributor Author

@jasnell, could you approve this pull?

targos reviewed Sep 13, 2021
View reviewed changes
Comment thread doc/api/timers.md Outdated
aduh95 added the commit-queue Add this label to land a pull request using GitHub Actions. label Sep 16, 2021
github-actions Bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Sep 16, 2021

github-actions Bot commented Sep 16, 2021

Copy link
Copy Markdown
Contributor

Landed in c365145...de10ab2

github-actions Bot closed this Sep 16, 2021
nodejs-github-bot pushed a commit that referenced this pull request Sep 16, 2021
doc: add timeout.close
de10ab2 
PR-URL: #40036
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
BethGriggs pushed a commit that referenced this pull request Sep 21, 2021
doc: add timeout.close
edec15b 
PR-URL: #40036
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
BethGriggs pushed a commit that referenced this pull request Sep 21, 2021
doc: add timeout.close
7fdb127 
PR-URL: #40036
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
BethGriggs mentioned this pull request Sep 21, 2021
Merged
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

tniessen tniessen approved these changes
aduh95 aduh95 approved these changes
jasnell Awaiting requested review from jasnell
+1 more reviewer
targos targos approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

author ready PRs that have at least one approval, no outstanding review comments, and a CI started. doc Issues and PRs related to the documentations. timers Issues and PRs related to the timers subsystem / setImmediate, setInterval, setTimeout.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

Back | FazBrowse Home | New Git URL