doc: improve `util._extend` function #8187

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
8 participants
@thefourtheye
Contributor

thefourtheye commented Aug 19, 2016

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

@princejwesley

View changes

doc/api/util.md
+ // { name: 'Node.js' }
+console.log(util._extend({'name': 'Node', 'lang': 'js'}, {'name': 'Node.js'}));
+ // { name: 'Node.js', lang: 'js' }
+```

This comment has been minimized.

@princejwesley

princejwesley Aug 19, 2016

Contributor

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

@princejwesley

princejwesley Aug 19, 2016

Contributor

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

This comment has been minimized.

@thefourtheye

thefourtheye Aug 19, 2016

Contributor

True. But we have done that in log too

@thefourtheye

thefourtheye Aug 19, 2016

Contributor

True. But we have done that in log too

@cjihrig

This comment has been minimized.

Show comment
Hide comment
@cjihrig

cjihrig Aug 19, 2016

Contributor

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

Contributor

cjihrig commented Aug 19, 2016

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

@cjihrig

This comment has been minimized.

Show comment
Hide comment
@cjihrig

cjihrig Aug 19, 2016

Contributor

Although maybe updating the function signature is appropriate :-)

Contributor

cjihrig commented Aug 19, 2016

Although maybe updating the function signature is appropriate :-)

@mscdex

This comment has been minimized.

Show comment
Hide comment
@mscdex

mscdex Aug 19, 2016

Contributor

-1 to all but the function signature change.

Contributor

mscdex commented Aug 19, 2016

-1 to all but the function signature change.

@jasnell

This comment has been minimized.

Show comment
Hide comment
@jasnell

jasnell Aug 19, 2016

Member

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

Member

jasnell commented Aug 19, 2016

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

@thefourtheye

This comment has been minimized.

Show comment
Hide comment
@thefourtheye

thefourtheye Aug 20, 2016

Contributor

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

Contributor

thefourtheye commented Aug 20, 2016

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

@yorkie

View changes

doc/api/util.md
@@ -666,7 +666,7 @@ Deprecated predecessor of `console.log`.
Deprecated predecessor of `console.log`.
-### util._extend(obj)
+### util._extend(targetObj, sourceObj)

This comment has been minimized.

@yorkie

yorkie Aug 20, 2016

Member

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

@yorkie

yorkie Aug 20, 2016

Member

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

This comment has been minimized.

@princejwesley

princejwesley Aug 20, 2016

Contributor

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

@princejwesley

princejwesley Aug 20, 2016

Contributor

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

This comment has been minimized.

@yorkie

yorkie Aug 20, 2016

Member

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

@yorkie

yorkie Aug 20, 2016

Member

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

This comment has been minimized.

@princejwesley

princejwesley Aug 20, 2016

Contributor

@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)

@princejwesley

princejwesley Aug 20, 2016

Contributor

@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)

This comment has been minimized.

@yorkie

yorkie Aug 20, 2016

Member

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

@yorkie

yorkie Aug 20, 2016

Member

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

@jasnell

This comment has been minimized.

Show comment
Hide comment
@jasnell

jasnell Aug 21, 2016

Member

LGTM

Member

jasnell commented Aug 21, 2016

LGTM

@thefourtheye

This comment has been minimized.

Show comment
Hide comment
@thefourtheye

thefourtheye Aug 23, 2016

Contributor

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

Contributor

thefourtheye commented Aug 23, 2016

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

@targos

This comment has been minimized.

Show comment
Hide comment
@targos

targos Aug 23, 2016

Member

LGTM

Member

targos commented Aug 23, 2016

LGTM

@yorkie

This comment has been minimized.

Show comment
Hide comment
@yorkie

yorkie Aug 23, 2016

Member

LGTM :-)

Member

yorkie commented Aug 23, 2016

LGTM :-)

@jasnell

This comment has been minimized.

Show comment
Hide comment
@jasnell

jasnell Aug 23, 2016

Member

@cjihrig and @mscdex ... PTAL

Member

jasnell commented Aug 23, 2016

@cjihrig and @mscdex ... PTAL

@mscdex

This comment has been minimized.

Show comment
Hide comment
@mscdex

mscdex Aug 23, 2016

Contributor

LGTM

Contributor

mscdex commented Aug 23, 2016

LGTM

@jasnell

This comment has been minimized.

Show comment
Hide comment
@jasnell

jasnell Aug 23, 2016

Member

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

Member

jasnell commented Aug 23, 2016

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

@thefourtheye

This comment has been minimized.

Show comment
Hide comment
@thefourtheye

thefourtheye Aug 24, 2016

Contributor

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

Contributor

thefourtheye commented Aug 24, 2016

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

util: improve function signature of util._extend
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>
@thefourtheye

This comment has been minimized.

Show comment
Hide comment
@thefourtheye

thefourtheye Aug 26, 2016

Contributor

Landed in b3e7ac2

Contributor

thefourtheye commented Aug 26, 2016

Landed in b3e7ac2

@thefourtheye thefourtheye deleted the thefourtheye:doc-fix-util-extend branch Aug 26, 2016

thefourtheye added a commit that referenced this pull request Aug 26, 2016

util: improve function signature of util._extend
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>

@Fishrock123 Fishrock123 referenced this pull request Sep 6, 2016

Closed

v6.6.0 pre-proposal #8428

Fishrock123 added a commit to Fishrock123/node that referenced this pull request Sep 8, 2016

util: improve function signature of util._extend
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 added a commit that referenced this pull request Sep 9, 2016

util: improve function signature of util._extend
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>

@piascikj piascikj referenced this pull request in imdone/node Oct 3, 2017

Open

add see ticket #8187 #141

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment