doc: better example & synopsis

PR-URL: #6167
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Robert Jefe Lindstädt <[email protected]>

doc/api/_toc.markdown

@@ -1,7 +1,7 @@
 @// NB(chrisdickinson): if you move this file, be sure to update tools/doc/html.js to
 @// point at the new location.
 * [About these Docs](documentation.html)
-* [Synopsis](synopsis.html)
+* [Usage & Example](synopsis.html)
 * [Assertion Testing](assert.html)
 * [Buffer](buffer.html)
 * [C/C++ Addons](addons.html)

doc/api/synopsis.markdown

@@ -1,29 +1,43 @@
-# Synopsis
+# Usage
 
 <!--type=misc-->
 
+`node [options] [v8 options] [script.js | -e "script"] [arguments]`
+
+Please see the [Command Line Options][] document for information about
+different options and ways to run scripts with Node.
+
+## Example
+
 An example of a [web server][] written with Node.js which responds with
 `'Hello World'`:
 
 ```js
 const http = require('http');
 
-http.createServer( (request, response) => {
-  response.writeHead(200, {'Content-Type': 'text/plain'});
-  response.end('Hello World\n');
-}).listen(8124);
+const hostname = '127.0.0.1';
+const port = 3000;
+
+const server = http.createServer((req, res) => {
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/plain');
+  res.end('Hello World\n');
+});
 
-console.log('Server running at http://127.0.0.1:8124/');
+server.listen(port, hostname, () => {
+  console.log(`Server running at http://${hostname}:${port}/`);
+});
 ```
 
 To run the server, put the code into a file called `example.js` and execute
-it with the node program
+it with Node.js:
 
 ```
 $ node example.js
-Server running at http://127.0.0.1:8124/
+Server running at http://127.0.0.1:3000/
 ```
 
 All of the examples in the documentation can be run similarly.
 
+[Command Line Options]: cli.html#cli_command_line_options
 [web server]: http.html