From 7c5283d60761b23090549d52b00f489666d4877d Mon Sep 17 00:00:00 2001
From: Tevin Zhang <mail2tevin@gmail.com>
Date: Mon, 11 Feb 2019 18:42:37 +0800
Subject: [PATCH] Refine doc

---
 README.md        | 34 +++++++++++++++++++---------------
 checker_linux.go | 30 ------------------------------
 doc.go           | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 53 insertions(+), 45 deletions(-)
 create mode 100644 doc.go

diff --git a/README.md b/README.md
index 023f3be..5b264f1 100644
--- a/README.md
+++ b/README.md
@@ -3,39 +3,41 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/tevino/tcp-shaker)](https://goreportcard.com/report/github.com/tevino/tcp-shaker)
 [![GoDoc](https://godoc.org/github.com/tevino/tcp-shaker?status.svg)](https://godoc.org/github.com/tevino/tcp-shaker)
 
-Performing TCP handshake without ACK, useful for health checking.
+This package is used to perform TCP handshake without ACK, which useful for TCP health checking.
 
 HAProxy does this exactly the same, which is:
 
-- SYN
-- SYN-ACK
-- RST
+1. SYN
+2. SYN-ACK
+3. RST
 
-## Why do I have to do this?
+## Why do I have to do this
 
-Usually when you establish a TCP connection(e.g. `net.Dial`), these are the first three packets (TCP three-way handshake):
+In most cases when you establish a TCP connection(e.g. via `net.Dial`), these are the first three packets between the client and server([TCP three-way handshake][tcp-handshake]):
 
-- Client -> Server: SYN
-- Server -> Client: SYN-ACK
-- Client -> Server: ACK
+1. Client -> Server: SYN
+2. Server -> Client: SYN-ACK
+3. Client -> Server: ACK
 
 **This package tries to avoid the last ACK when doing handshakes.**
 
 By sending the last ACK, the connection is considered established.
 
-However as for TCP health checking the last ACK may not necessary.
+However, as for TCP health checking the server could be considered alive right after it sends back SYN-ACK,
 
-The Server could be considered alive after it sends back SYN-ACK.
+that renders the last ACK unnecessary or even harmful in some cases.
 
-### Benefits of avoiding the last ACK
+### Benefits
+
+By avoiding the last ACK
 
 1. Less packets better efficiency
 2. The health checking is less obvious
 
-The second one is essential, because it bothers server less.
+The second one is essential because it bothers the server less.
 
-Usually this means the server will not notice the health checking traffic at all, **thus the act of health checking will not be
-considered as some misbehaviour of client.**
+This means the application level server will not notice the health checking traffic at all, **thus the act of health checking will not be
+considered as some misbehavior of client.**
 
 ## Requirements
 
@@ -77,3 +79,5 @@ conn.Close()
 ## TODO
 
 - [ ] IPv6 support (Test environment needed, PRs are welcome)
+
+[tcp-handshake]: https://en.wikipedia.org/wiki/Handshaking#TCP_three-way_handshake
\ No newline at end of file
diff --git a/checker_linux.go b/checker_linux.go
index 9e20d03..37b7010 100644
--- a/checker_linux.go
+++ b/checker_linux.go
@@ -1,33 +1,3 @@
-// Package tcp is used to perform TCP handshake without ACK,
-// useful for health checking, HAProxy does this exactly the same.
-// Which is SYN, SYN-ACK, RST.
-//
-// Why do I have to do this?
-// Usually when you establish a TCP connection(e.g. net.Dial), these
-// are the first three packets (TCP three-way handshake):
-//
-//	SYN:     Client -> Server
-//	SYN-ACK: Server -> Client
-//	ACK:     Client -> Server
-//
-// This package tries to avoid the last ACK when doing handshakes.
-//
-// By sending the last ACK, the connection is considered established.
-// However as for TCP health checking the last ACK may not necessary.
-// The Server could be considered alive after it sends back SYN-ACK.
-//
-// Benefits of avoiding the last ACK:
-//
-// 1. Less packets better efficiency
-//
-// 2. The health checking is less obvious
-//
-// The second one is essential, because it bothers server less.
-// Usually this means the server will not notice the health checking
-// traffic at all, thus the act of health checking will not be
-// considered as some misbehaviour of client.
-//
-// Checker's methods may be called by multiple goroutines simultaneously.
 package tcp
 
 import (
diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..c008485
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,34 @@
+/*
+Package tcp is used to perform TCP handshake without ACK, which useful for TCP health checking.
+HAProxy does this exactly the same, which is:
+
+	1. SYN
+	2. SYN-ACK
+	3. RST
+
+Why do I have to do this
+
+In most cases when you establish a TCP connection(e.g. via net.Dial), these are the first three packets between the client and server(TCP three-way handshake):
+
+	1. Client -> Server: SYN
+	2. Server -> Client: SYN-ACK
+	3. Client -> Server: ACK
+
+This package tries to avoid the last ACK when doing handshakes.
+
+By sending the last ACK, the connection is considered established.
+
+However, as for TCP health checking the server could be considered alive right after it sends back SYN-ACK, that renders the last ACK unnecessary or even harmful in some cases.
+
+Benefits
+
+By avoiding the last ACK
+
+	1. Less packets better efficiency
+	2. The health checking is less obvious
+
+The second one is essential because it bothers the server less.
+
+This means the application level server will not notice the health checking traffic at all, thus the act of health checking will not be considered as some misbehavior of client.
+*/
+package tcp