Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add comment for net.Server's error event #11136

Closed
wants to merge 1 commit into from

Conversation

jjqq2013
Copy link
Contributor

@jjqq2013 jjqq2013 commented Feb 3, 2017

Fix: #9710

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

doc

@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. net Issues and PRs related to the net subsystem. labels Feb 3, 2017
Copy link
Member

@addaleax addaleax left a comment

Choose a reason for hiding this comment

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

Looks good, with a small nit.

Two things regarding the commit message though:

  1. Your author name in this commit is given as “q”. Is that intended or do you prefer to be listed (changelog, git log, AUTHORS file) with some other name? People typically prefer their full name, but ultimately it’s up to you.

  2. Could you use Fixes: instead of Fix:? 😄 It’s not important, but the former is more commonly used around here.

doc/api/net.md Outdated
@@ -40,8 +40,9 @@ added: v0.1.90

* {Error}

Emitted when an error occurs. The [`'close'`][] event will be called directly
following this event. See example in discussion of `server.listen`.
Emitted when an error occurs. Unlike the [`net.Socket`][], the [`'close'`][]
Copy link
Member

Choose a reason for hiding this comment

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

Can you drop the, or replace it with with? (not a native speaker myself but the the sounds odd here)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Of course, thank you!

@jjqq2013 jjqq2013 force-pushed the doc-server-error branch 2 times, most recently from ef32fb1 to 5cbd17a Compare February 3, 2017 07:27
doc/api/net.md Outdated
following this event. See example in discussion of `server.listen`.
Emitted when an error occurs. Unlike [`net.Socket`][], the [`'close'`][]
event will NOT be called directly following this event, unless you call
`server.close()` manually. See example in discussion of `server.listen`.
Copy link
Member

Choose a reason for hiding this comment

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

Please avoid the use of pronouns like you in the documentation. Also, please use either italics or bold for emphasis as opposed to upper case (e.g. NOT) This can be reworded as:

Emitted when an error occurs., Unlike [`net.Socket'`[], the [`'close'`][]
event will **not** be called directly following this event unless
`server.close()` is manually called. See the example in the discussion
of `server.listen()`.

Copy link
Contributor Author

@jjqq2013 jjqq2013 Feb 4, 2017

Choose a reason for hiding this comment

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

Thanks.

The net.Socket is not an event, so can not be displayed as a link by ['net.Socket'][], this is why i just use [net.Socket][].

Besides, "See the example in the discussion", two "the" seems odd? So i stripped second "the".

See my second commit's preview: https://github.com/sjitech/node/blob/3b440d3db2a2dfa9833eb06ede6f1adb909c1644/doc/api/net.md#event-error

@jjqq2013
Copy link
Contributor Author

jjqq2013 commented Feb 5, 2017

The http.Server has the same behavior, but i can not found any description about 'error' event of http.Server, should we add same note?

doc/api/net.md Outdated
Emitted when an error occurs. The [`'close'`][] event will be called directly
following this event. See example in discussion of `server.listen`.
Emitted when an error occurs. Unlike [`net.Socket`][], the [`'close'`][]
event will **not** be called directly following this event unless
Copy link
Contributor

Choose a reason for hiding this comment

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

events are "emitted", not "called"

Copy link
Contributor Author

Choose a reason for hiding this comment

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

ok, i will correct it and the original description.

@sam-github
Copy link
Contributor

The http.Server has the same behavior, but i can not found any description about 'error' event of http.Server, should we add same note?

Yes.

@jjqq2013
Copy link
Contributor Author

sorry, i found the http.Server has already mentioned

This class inherits from net.Server and has the following additional events

So i think no need to add description of error event.

doc/api/net.md Outdated
Emitted when an error occurs. Unlike [`net.Socket`][], the [`'close'`][]
event will **not** be emitted directly following this event unless
`server.close()` is manually called. See the example in discussion of
`server.listen()`.
Copy link
Contributor

Choose a reason for hiding this comment

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

would be good to link server.close() and server.listen()

Copy link
Member

Choose a reason for hiding this comment

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

@QianJin2013 ... please see @sam-github's comment above :-)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@sam-github I'd tried to link server.close() and server.listen() but failed. Now i know the reason, i have modified doc again.

@sam-github
Copy link
Contributor

you'll need to squash and rebase

@jjqq2013
Copy link
Contributor Author

@sam-github yes, i will squash and rebase it.

@jjqq2013 jjqq2013 force-pushed the doc-server-error branch 3 times, most recently from 6eb63c9 to 72b4bd3 Compare February 17, 2017 02:13
@sam-github
Copy link
Contributor

Landed in 52ddb41. thanks.

@sam-github sam-github closed this Feb 20, 2017
sam-github pushed a commit that referenced this pull request Feb 20, 2017
Fixes: #9710
PR-URL: #11136
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
addaleax pushed a commit that referenced this pull request Feb 22, 2017
Fixes: #9710
PR-URL: #11136
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
@italoacasas italoacasas mentioned this pull request Feb 25, 2017
jasnell pushed a commit that referenced this pull request Mar 7, 2017
Fixes: #9710
PR-URL: #11136
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
jasnell pushed a commit that referenced this pull request Mar 7, 2017
Fixes: #9710
PR-URL: #11136
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
Fixes: #9710
PR-URL: #11136
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
@MylesBorins MylesBorins mentioned this pull request Mar 9, 2017
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
Fixes: #9710
PR-URL: #11136
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
@MylesBorins MylesBorins mentioned this pull request Mar 9, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. net Issues and PRs related to the net subsystem.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

doc issue: socket server 'error' event: 'close' is not called as described in doc.
5 participants