Skip to content

doc: improve util._extend function - #8187

Closed
thefourtheye wants to merge 1 commit into
nodejs:masterfrom
thefourtheye:doc-fix-util-extend
Closed

doc: improve util._extend function#8187
thefourtheye wants to merge 1 commit into
nodejs:masterfrom
thefourtheye:doc-fix-util-extend

Conversation

@thefourtheye

@thefourtheyethefourtheye commented Aug 19, 2016

Copy link
Copy Markdown
Contributor
Checklist
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc, util

Description of change

improve util._extend function's documentation

@thefourtheyethefourtheye added util Issues and PRs related to the built-in util module. doc Issues and PRs related to the documentations. labels Aug 19, 2016
princejwesley
princejwesley reviewed Aug 19, 2016
View reviewed changes
Comment threaddoc/api/util.md Outdated

@princejwesleyprincejwesleyAug 19, 2016

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.

@thefourtheye Do we need an example for deprecated function? its like warn users and teach them how to use it 😄

@thefourtheyethefourtheyeAug 19, 2016

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

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

True. But we have done that in log too

@cjihrig

cjihrig commented Aug 19, 2016

Copy link
Copy Markdown
Contributor

Thanks for the PR, but I'm not sure that we should improve the docs for this function.

@cjihrig

cjihrig commented Aug 19, 2016

Copy link
Copy Markdown
Contributor

Although maybe updating the function signature is appropriate :-)

@mscdex

mscdex commented Aug 19, 2016

Copy link
Copy Markdown
Contributor

-1 to all but the function signature change.

@jasnell

jasnell commented Aug 19, 2016

Copy link
Copy Markdown
Member

Given the deprecated status, I agree that we likely shouldn't extend the documentation on this.

@thefourtheye

thefourtheye commented Aug 20, 2016

Copy link
Copy Markdown
ContributorAuthor

Okay. Fixed the function signature alone now. Hope this is okay.

yorkie
yorkie reviewed Aug 20, 2016
View reviewed changes
Comment threaddoc/api/util.md Outdated

@yorkieyorkieAug 20, 2016

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.

Should be origin and add to keep consistent with source, see https://github.com/nodejs/node/blob/master/lib/util.js#L976

@princejwesleyprincejwesleyAug 20, 2016

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.

why not util._extend(target, source) without obj suffix ? @yorkieorigin/add combination is confusing.

@yorkieyorkieAug 20, 2016

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.

Both look good to me, but consistence should be considered here.

@princejwesleyprincejwesleyAug 20, 2016•
edited
Loading

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.

@yorkie In the case of origin/add pair, I have code in place to understand what the particular function does. But documentation is the face of the code and we can not expect user to read the code in case of doubt. Its my humble opinion. ( extend the target from source)

@yorkieyorkieAug 20, 2016

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.

@princejwesley Why do we not change the source to target/source, too?

@jasnell

jasnell commented Aug 21, 2016

Copy link
Copy Markdown
Member

LGTM

@thefourtheye

thefourtheye commented Aug 23, 2016

Copy link
Copy Markdown
ContributorAuthor

@yorkie@princejwesley Renamed the parameter names, for clarity. PTAL.

@targos

targos commented Aug 23, 2016

Copy link
Copy Markdown
Member

LGTM

@yorkie

yorkie commented Aug 23, 2016

Copy link
Copy Markdown
Contributor

LGTM :-)

@jasnell

jasnell commented Aug 23, 2016

Copy link
Copy Markdown
Member

@cjihrig and @mscdex ... PTAL

@mscdex

mscdex commented Aug 23, 2016

Copy link
Copy Markdown
Contributor

LGTM

@jasnell

jasnell commented Aug 23, 2016

Copy link
Copy Markdown
Member

@thefourtheye ... can you please rebase and update this?

@thefourtheye
thefourtheyeforce-pushed the doc-fix-util-extend branch 2 times, most recently from 5e1a699 to 7aa1e22CompareAugust 24, 2016 04:53
@thefourtheye

thefourtheye commented Aug 24, 2016

Copy link
Copy Markdown
ContributorAuthor

@jasnell Done. I'll land this tomorrow, if there are no other suggestions.

@thefourtheye
util: improve function signature of util._extend
a8c7221
The function signature of `util._extend` is not intuitive and the
documentation doesn't specify the necessary second parameter. This
patch changes the parameter names in the code and the function params
in doc.
PR-URL: nodejs#8187
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
@thefourtheye

thefourtheye commented Aug 26, 2016

Copy link
Copy Markdown
ContributorAuthor

Landed in b3e7ac2

@thefourtheye
thefourtheye deleted the doc-fix-util-extend branch August 26, 2016 13:29
thefourtheye added a commit that referenced this pull request Aug 26, 2016
@thefourtheye
util: improve function signature of util._extend
b3e7ac2
The function signature of `util._extend` is not intuitive and the
documentation doesn't specify the necessary second parameter. This
patch changes the parameter names in the code and the function params
in doc.
PR-URL: #8187
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
@Fishrock123Fishrock123 mentioned this pull request Sep 6, 2016
Closed
Fishrock123 pushed a commit to Fishrock123/node that referenced this pull request Sep 8, 2016
@thefourtheye@Fishrock123
util: improve function signature of util._extend
39d1ee3
The function signature of `util._extend` is not intuitive and the
documentation doesn't specify the necessary second parameter. This
patch changes the parameter names in the code and the function params
in doc.
PR-URL: nodejs#8187
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
Fishrock123 pushed a commit that referenced this pull request Sep 9, 2016
@thefourtheye@Fishrock123
util: improve function signature of util._extend
d67ece2
The function signature of `util._extend` is not intuitive and the
documentation doesn't specify the necessary second parameter. This
patch changes the parameter names in the code and the function params
in doc.
PR-URL: #8187
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
@piascikjpiascikj mentioned this pull request Oct 3, 2017
Open
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docIssues and PRs related to the documentations.utilIssues and PRs related to the built-in util module.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

8 participants

@thefourtheye@cjihrig@mscdex@jasnell@targos@yorkie@princejwesley@MylesBorins