doc: add timeout.close

[galkin]

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);
	returnthis;
	};

This pull adds documentation for this method.

[aduh95]

Thanks for opening this!

[tniessen]

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

[galkin]

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]

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]

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

[galkin]

@jasnell, could you approve this pull?

[github-actions]

Landed in c365145...de10ab2