Update docs

ipblocklist/files/http.go

@@ -40,6 +40,8 @@ func (h httpFile) String() string {
 	return h.url
 }
 
+// NewHTTP returns a file abstraction for HTTP/HTTPS endpoint. You also need to
+// provide a valid instance of [http.Client] to access it.
 func NewHTTP(client *http.Client, endpoint string) (File, error) {
 	if client == nil {
 		return nil, ErrBadHTTPClient

ipblocklist/files/init.go

@@ -6,9 +6,16 @@ import (
 	"io"
 )
 
+// ErrBadHTTPClient is returned if given HTTP client is initialized
+// incorrectly.
 var ErrBadHTTPClient = errors.New("incorrect http client")
 
+// File is an abstraction for a entity that can be opened in some context.
 type File interface {
+	// Open returns an readable entity for a file. It is important to not forget
+	// to close it after the usage.
 	Open(context.Context) (io.ReadCloser, error)
+
+	// String returns a short text description for the file
 	String() string
 }

ipblocklist/files/local.go

@@ -19,6 +19,7 @@ func (l localFile) String() string {
 	return l.path
 }
 
+// NewLocal returns an openable File for a path on a local file system.
 func NewLocal(path string) (File, error) {
 	if stat, err := os.Stat(path); os.IsNotExist(err) || stat.IsDir() || stat.Mode().Perm()&0o400 == 0 {
 		return nil, fmt.Errorf("%s is not a readable file", path)

ipblocklist/files/mem.go

@@ -19,6 +19,7 @@ func (m memFile) String() string {
 	return "mem"
 }
 
+// NewMem returns an openable file that is kept in RAM.
 func NewMem(networks []*net.IPNet) File {
 	builder := strings.Builder{}
 

ipblocklist/firehol.go

@@ -27,19 +27,19 @@ var (
 // execute when ip list is updated.
 type FireholUpdateCallback func(context.Context, int)
 
-// Firehol is IPBlocklist which uses lists from FireHOL:
+// Firehol is [mtglib.IPBlocklist] which uses lists from FireHOL:
 // https://iplists.firehol.org/
 //
-// It can use both local files and remote URLs. This is not necessary
-// that blocklists should be taken from this website, we expect only
-// compatible formats here.
+// It can use both local files and remote URLs. This is not necessary that
+// blocklists should be taken from this website, we expect only compatible
+// formats here.
 //
 // Example of the format:
 //
-//     # this is a comment
-//     # to ignore
-//     127.0.0.1   # you can specify an IP
-//     10.0.0.0/8  # or cidr
+//	# this is a comment
+//	# to ignore
+//	127.0.0.1   # you can specify an IP
+//	10.0.0.0/8  # or cidr
 type Firehol struct {
 	ctx         context.Context
 	ctxCancel   context.CancelFunc
@@ -78,8 +78,7 @@ func (f *Firehol) Contains(ip net.IP) bool {
 
 // Run starts a background update process.
 //
-// This is a blocking method so you probably want to run it in a
-// goroutine.
+// This is a blocking method so you probably want to run it in a goroutine.
 func (f *Firehol) Run(updateEach time.Duration) {
 	if updateEach == 0 {
 		updateEach = DefaultFireholUpdateEach
@@ -211,8 +210,8 @@ func (f *Firehol) updateParseLine(text string) (*net.IPNet, error) {
 
 // NewFirehol creates a new instance of FireHOL IP blocklist.
 //
-// This method does not start an update process so please execute Run
-// when it is necessary.
+// This method does not start an update process so please execute Run when it
+// is necessary.
 func NewFirehol(logger mtglib.Logger, network mtglib.Network,
 	downloadConcurrency uint,
 	urls []string,
@@ -244,6 +243,9 @@ func NewFirehol(logger mtglib.Logger, network mtglib.Network,
 	return NewFireholFromFiles(logger, downloadConcurrency, blocklists, updateCallback)
 }
 
+// NewFirehol creates a new instance of FireHOL IP blocklist.
+//
+// This method creates this instances from a given list of files.
 func NewFireholFromFiles(logger mtglib.Logger,
 	downloadConcurrency uint,
 	blocklists []files.File,

ipblocklist/init.go

@@ -1,8 +1,8 @@
 // Package ipblocklist contains default implementation of the
-// IPBlocklist for mtg.
+// [mtglib.IPBlocklist] for mtg.
 //
-// Please check documentation for mtglib.IPBlocklist interface to get an
-// idea of this abstraction.
+// Please check documentation for [mtglib.IPBlocklist] interface to get an idea
+// of this abstraction.
 package ipblocklist
 
 import "time"
@@ -12,7 +12,7 @@ const (
 	// concurrent downloads of ip blocklists for Firehol.
 	DefaultFireholDownloadConcurrency = 1
 
-	// DefaultFireholUpdateEach defines a default time period when
-	// Firehol requests updates of the blocklists.
+	// DefaultFireholUpdateEach defines a default time period when Firehol
+	// requests updates of the blocklists.
 	DefaultFireholUpdateEach = 6 * time.Hour
 )

ipblocklist/noop.go

@@ -13,8 +13,7 @@ func (n noop) Contains(ip net.IP) bool      { return false }
 func (n noop) Run(updateEach time.Duration) {}
 func (n noop) Shutdown()                    {}
 
-// NewNoop returns a dummy ipblocklist which allows all incoming
-// connections.
+// NewNoop returns a dummy ipblocklist which allows all incoming connections.
 func NewNoop() mtglib.IPBlocklist {
 	return noop{}
 }