Merge pull request #49 from goodhosts/readme

updating readme and comments

README.md

@@ -1,64 +1,62 @@
-# Go library for working with a system's hostsfile
-[![codecov](https://codecov.io/gh/goodhosts/hostsfile/branch/master/graph/badge.svg?token=BJQH16QQEH)](https://codecov.io/gh/goodhosts/hostsfile)
-## Usage
+# Go package for working with a system's hostsfile
+[![codecov](https://codecov.io/gh/goodhosts/hostsfile/branch/main/graph/badge.svg?token=BJQH16QQEH)](https://codecov.io/gh/goodhosts/hostsfile)
+[![Go Reference](https://pkg.go.dev/badge/github.com/goodhosts/hostsfile.svg)](https://pkg.go.dev/github.com/goodhosts/hostsfile)
 
-Using system default hosts file
+Reads the content of a file in the [hosts format](https://en.wikipedia.org/wiki/Hosts_(file)) into go structs for easy manipulation in go programs. When all changes are complete you can `Flush` the hosts file back to disk to save your changes. Supports an indexing system on both ips and hosts for quick management of large hosts files.    
+
+## Simple Usage
+Simple usage reading in your system's hosts file and adding an entry for the ip `192.168.1.1` and the host `my-hostname`
+
+```go
+package main
+
+import (
+	"log"
+
+	"github.com/goodhosts/hostsfile"
+)
+
+func main() {
+    hosts, err := hostsfile.NewHosts()
+    if err != nil {
+        log.Fatal(err.Error())
+    }
+    if err := hosts.Add("192.168.1.1", "my-hostname"); err != nil {
+        log.Fatal(err.Error())
+    }
+    if err := hosts.Flush(); err != nil {
+        log.Fatal(err.Error())
+    }
+}
 ```
-hfile, err := hostsfile.NewHosts()
+
+### Other Usage
+Read in a hosts file from a custom location which is not the system default, this is useful for tests or systems with non-standard hosts file locations.
+```
+hosts, err := hostsfile.NewCustomHosts("./my-custom-hostsfile")
 ```
 
-Using a custom hostsfile at a specific location
+Use `Add` to put an ip and host combination in the hosts file
 ```
-hfile, err := hostsfile.NewCustomHosts("./my-custom-hostsfile")
+err := hosts.Add("192.168.1.1", "my-hostname")
 ```
 
-Add an ip entry with it's hosts
+`Add` is variadic and can take multiple hosts to add for the same ip
 ```
-err := hfile.Add("192.168.1.1", "my-hostname", "another-hostname")
+err := hosts.Add("192.168.1.1", "my-hostname", "another-hostname")
 ```
 
-Remove an ip/host combination
+Use `Remove` to drop an ip and host combination from the hosts file
 ```
-err := hfile.Remove("192.168.1.1", "another-hostname")
+err := hosts.Remove("192.168.1.1", "my-hostname")
 ```
 
-Flush the hostfile changes back to disk
+`Remove` is variadic and can take multiple hosts to remove from the same ip
 ```
-err := hfile.Flush()
+err := hosts.Remove("192.168.1.1", "my-hostname", "another-hostname")
 ```
 
-# Full API
+Flush the hosts file changes back to disk
+```
+err := hosts.Flush()
 ```
-type Hosts
-func NewCustomHosts(osHostsFilePath string) (*Hosts, error)
-    func NewHosts() (*Hosts, error)
-    func (h *Hosts) Add(ip string, hosts ...string) error
-    func (h *Hosts) AddRaw(raw ...string) error
-    func (h *Hosts) Clean()
-    func (h *Hosts) Clear()
-    func (h *Hosts) Flush() error
-    func (h *Hosts) Has(ip string, host string) bool
-    func (h *Hosts) HasHostname(host string) bool
-    func (h *Hosts) HasIp(ip string) bool
-    func (h *Hosts) HostsPerLine(count int)
-    func (h *Hosts) IsWritable() bool
-    func (h *Hosts) Load() error
-    func (h *Hosts) Remove(ip string, hosts ...string) error
-    func (h *Hosts) RemoveByHostname(host string) error
-    func (h *Hosts) RemoveByIp(ip string) error
-    func (h *Hosts) RemoveDuplicateHosts()
-    func (h *Hosts) RemoveDuplicateIps()
-    func (h *Hosts) SortByIp()
-    func (h *Hosts) SortHosts()
-type HostsLine
-func NewHostsLine(raw string) HostsLine
-    func (l *HostsLine) Combine(hostline HostsLine)
-    func (l *HostsLine) HasComment() bool
-    func (l *HostsLine) IsComment() bool
-    func (l *HostsLine) IsMalformed() bool
-    func (l *HostsLine) IsValid() bool
-    func (l *HostsLine) RegenRaw()
-    func (l *HostsLine) RemoveDuplicateHosts()
-    func (l *HostsLine) SortHosts()
-    func (l *HostsLine) ToRaw() string
-```

hosts.go

@@ -14,9 +14,11 @@ import (
 	"github.com/dimchansky/utfbom"
 )
 
+// Hosts represents hosts file with the path and parsed contents of each line
 type Hosts struct {
-	Path  string
-	Lines []HostsLine
+	Path  string      // Path to the location of the hosts file that will be loaded/flushed
+	Lines []HostsLine // Slice containing all the lines parsed from the hosts file
+
 	ips   lookup
 	hosts lookup
 }
@@ -361,7 +363,7 @@ func (h *Hosts) combineIP(ip string) {
 	for _, line := range lines {
 		if line.IP == ip {
 			// if you find the ip combine it into newline
-			newLine.Combine(line)
+			newLine.combine(line)
 			continue
 		}
 		// add everyone else

hostsline.go

@@ -7,17 +7,19 @@ import (
 	"strings"
 )
 
+// HostsLine represents a line of the hosts file after being parsed into their respective parts
 type HostsLine struct {
-	IP      string
-	Hosts   []string
-	Raw     string
-	Err     error
-	Comment string
+	IP      string   // IP found at the beginning of the line
+	Hosts   []string // Hosts split into a slice on the space char
+	Comment string   // Contents of everything after the comment char in the line
+
+	Raw string // Raw contents of the line as parsed in or updated after changes
+	Err error  // Used for error checking during parsing
 }
 
 const commentChar string = "#"
 
-// NewHostsLine return a new instance of HostsLine.
+// NewHostsLine takes a raw line as a string and parses it into a new instance of HostsLine e.g. "192.168.1.1 host1 host2 # comments"
 func NewHostsLine(raw string) HostsLine {
 	output := HostsLine{Raw: raw}
 
@@ -47,6 +49,12 @@ func NewHostsLine(raw string) HostsLine {
 	return output
 }
 
+// String to make HostsLine a fmt.Stringer
+func (l *HostsLine) String() string {
+	return l.ToRaw()
+}
+
+// ToRaw returns the HostsLine's contents as a raw string
 func (l *HostsLine) ToRaw() string {
 	var comment string
 	if l.IsComment() { //Whole line is comment
@@ -77,7 +85,11 @@ func (l *HostsLine) RemoveDuplicateHosts() {
 	l.RegenRaw()
 }
 
+// Deprecated: will be made internal, combines the hosts and comments of two lines together,
 func (l *HostsLine) Combine(hostline HostsLine) {
+	l.combine(hostline)
+}
+func (l *HostsLine) combine(hostline HostsLine) {
 	l.Hosts = append(l.Hosts, hostline.Hosts...)
 	if l.Comment == "" {
 		l.Comment = hostline.Comment