docs(README): modernize and move api to jsdocs

* code examples updated with latest syntax * code examples now include esm import line * removed $ from shell examples for copying
hertzg · Jul 19, 2020 · 8d32e00 · 8d32e00
1 parent 17625b6
commit 8d32e00
Showing 1 changed file with 27 additions and 64 deletions.
diff --git a/README.md b/README.md
@@ -34,38 +34,40 @@ Tested on 🐧 `linux` & 🍏 `osx` (both `amd64` and `arm64`), should work on
 ## Install
 
 ```bash
-$ npm install --save net-keepalive
+npm install --save net-keepalive
 ```
 
 ## Documentation
 
-The project includes TypeScript definitions file (`index.d.ts`) which gives an overview of the API exposed.
+You can find the [full API Reference Document (JSDoc)](https://hertzg.github.io/node-net-keepalive) published on our github pages.
 
-You can find the [full API Reference](https://hertzg.github.io/node-net-keepalive) published on our github pages.
+The project includes TypeScript definitions file (`index.d.ts`) which gives an overview of the API exposed.
 
 Documentation gets generated from JSDoc comments, feel free to improve them by sending pull requests.
 
 ## Demo
 
-```Javascript
-var Net = require('net')
-  , NetKeepAlive = require('net-keepalive')
-;
+```javascript
+const Net = require('net'),
+  NetKeepAlive = require('net-keepalive')
+// or
+import * as Net from 'net'
+import * as NetKeepAlive from 'net-keepalive'
 
 // Create a TCP Server
-var srv = Net.createServer(function(s){
+const srv = Net.createServer((s) => {
   console.log('Connected %j', s.address())
   // Doesn't matter what it does
   s.pipe(s)
-});
+})
 
 // Start on some port
-srv.listen(1337, function(){
+srv.listen(1337, () => {
   console.log('Listening on %j', srv.address())
-});
+})
 
 // Connect to that server
-var s = Net.createConnection({port:1337}, function(){
+const s = Net.createConnection({ port: 1337 }, () => {
   console.log('Connected to %j', s.address())
 
   //IMPORTANT: KeepAlive must be enabled for this to work
@@ -82,13 +84,13 @@ var s = Net.createConnection({port:1337}, function(){
 
   // Get TCP_KEEPCNT for this specific socket
   NetKeepAlive.getKeepAliveProbes(s) // 1
-});
+})
 ```
 
 Now using `iptables` add rule to drop all `tcp` packets on `INPUT` chain to port `1337`.
 
 ```bash
-$ iptables -I INPUT -m tcp -p tcp --dport 1337 -j DROP
+iptables -I INPUT -m tcp -p tcp --dport 1337 -j DROP
 ```
 
 If you were monitoring packets on `loopback` with `tcp.srcport == 1337 || tcp.dstport == 1337` filter in `wireshark`. You will see the following output:
@@ -100,71 +102,32 @@ Have fun!
 More info about `SO_KEEPALIVE` here: [TCP Keepalive HOWTO](http://tldp.org/HOWTO/TCP-Keepalive-HOWTO/)
 `C` Code examples here: [Examples](http://tldp.org/HOWTO/TCP-Keepalive-HOWTO/programming.html#examples)
 
-## API
+## Sample
 
 **_Note: For these methods to work you must enable `SO_KEEPALIVE` and set the `TCP_KEEPIDLE` options for socket using `Net.Socket`-s built in method [`socket.setKeepAlive([enable][, initialDelay])`](https://nodejs.org/api/net.html#net_socket_setkeepalive_enable_initialdelay) !_**
 
     TCP_KEEPIDLE (since Linux 2.4) The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes, if the socket option SO_KEEPALIVE has been set on this socket. This option should not be used in code intended to be portable.
 
 ```JavaScript
-var NetSocket = require('net-keepalive')
+const NetKeepAlive = require('net-keepalive')
+// or
+import * as NetKeepAlive from 'net-keepalive'
 
-// .....
-// get socket somehow
 // .....
 
-var enable = true                                           // enable SO_KEEPALIVE
-var initialDuration = 1000                                  // start probing after 1 second of inactivity
-socket.setKeepAlive(enable, initialDuration)                // sets SO_KEEPALIVE and TCP_KEEPIDLE
+const enable = true                                             // enable SO_KEEPALIVE
+const initialDuration = 1000                                    // start probing after 1 second of inactivity
+socket.setKeepAlive(enable, initialDuration)                    // sets SO_KEEPALIVE and TCP_KEEPIDLE
 
-var probeInterval = 1000                                    // after initialDuration send probes every 1 second
-NetSocket.setKeepAliveInterval(socket, probeInterval)       //sets TCP_KEEPINTVL
+const probeInterval = 1000                                      // after initialDuration send probes every 1 second
+NetKeepAlive.setKeepAliveInterval(socket, probeInterval)        //sets TCP_KEEPINTVL
 
-var maxProbesBeforeFail = 10                                // after 10 failed probes connection will be dropped
-NetSocket.setKeepAliveProbes(socket, maxProbesBeforeFail)   // sets TCP_KEEPCNT
+const maxProbesBeforeFail = 10                                  // after 10 failed probes connection will be dropped
+NetKeepAlive.setKeepAliveProbes(socket, maxProbesBeforeFail)    // sets TCP_KEEPCNT
 
-// ....
 // ....
 ```
 
-### setKeepAliveInterval(socket, msecs)
-
-- `socket` - `instanceof Net.Socket`- Socket to modify
-- `msecs` - `Number` - Time in milliseconds between KeepAlive probes.
-- Returns `true` on success
-
-Sets `TCP_KEEPINTVL` to `msecs` miliseconds (converted to seconds `int` internally) for the `socket` based on its file descriptor (`fd`)
-
-    TCP_KEEPINTVL (since Linux 2.4) The time (in seconds) between individual keepalive probes. This option should not be used in code intended to be portable.
-
-### getKeepAliveInterval(socket)
-
-- `socket` - `instanceof Net.Socket`- Socket to modify
-- Returns `msecs` - `Number` - Time in milliseconds between KeepAlive probes on success
-
-Gets `TCP_KEEPINTVL`. The `msecs` miliseconds (converted from seconds `int` internally) set for the `socket` based on its file descriptor (`fd`)
-
-    TCP_KEEPINTVL (since Linux 2.4) The time (in seconds) between individual keepalive probes. This option should not be used in code intended to be portable.
-
-### setKeepAliveProbes(socket, count)
-
-- `socket` - `instanceof Net.Socket`- Socket to modify
-- `count` - `Number` - Number of probes to send before dropping the connection
-- Returns `true` on success
-
-Sets `TCP_KEEPCNT` to `count` number of probes for the `socket` based on its file descriptor (`fd`)
-
-    TCP_KEEPCNT (since Linux 2.4) - The maximum number of keepalive probes TCP should send before dropping the connection. This option should not be used in code intended to be portable.
-
-### getKeepAliveProbes(socket)
-
-- `socket` - `instanceof Net.Socket`- Socket to modify
-- Returns `count` - `Number` - Number of probes to send before dropping the connection on success.
-
-Gets `TCP_KEEPCNT`. The `count` number of probes set for the `socket` based on its file descriptor (`fd`)
-
-    TCP_KEEPCNT (since Linux 2.4) - The maximum number of keepalive probes TCP should send before dropping the connection. This option should not be used in code intended to be portable.
-
 ## Code of Conduct
 
 See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)