doc: better example & synopsis

Fishrock123 · Fishrock123 · commit ab84d6904881 · 2016-05-03T20:20:34.000-04:00
PR-URL: #6167 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
diff --git a/doc/api/_toc.md b/doc/api/_toc.md
@@ -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)
diff --git a/doc/api/synopsis.md b/doc/api/synopsis.md
@@ -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
