Update package documentation (#866)

* update 'addressbook' package
* update 'keystore' package
* update 'jsonhttp' package

pkg/addressbook/addressbook.go

@@ -20,10 +20,13 @@ var _ Interface = (*store)(nil)
 
 var ErrNotFound = errors.New("addressbook: not found")
 
+// Interface is the AddressBook interface.
 type Interface interface {
 	GetPutter
 	Remover
+	// Overlays returns a list of all overlay addresses saved in addressbook.
 	Overlays() ([]swarm.Address, error)
+	// Addresses returns a list of all bzz.Address-es saved in addressbook.
 	Addresses() ([]bzz.Address, error)
 }
 
@@ -33,14 +36,17 @@ type GetPutter interface {
 }
 
 type Getter interface {
+	// Get returns pointer to saved bzz.Address for requested overlay address.
 	Get(overlay swarm.Address) (addr *bzz.Address, err error)
 }
 
 type Putter interface {
+	// Put saves relation between peer overlay address and bzz.Address address.
 	Put(overlay swarm.Address, addr bzz.Address) (err error)
 }
 
 type Remover interface {
+	// Remove removes overlay address.
 	Remove(overlay swarm.Address) error
 }
 
@@ -48,6 +54,7 @@ type store struct {
 	store storage.StateStorer
 }
 
+// New creates new addressbook for state storer.
 func New(storer storage.StateStorer) Interface {
 	return &store{
 		store: storer,

pkg/addressbook/doc.go

+// Copyright 2020 The Swarm Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package addressbook provides persisted mapping between overlay (topology) address
+and bzz.Address address, which contains underlay (physical) address.
+The underlay address contains both physical and p2p addresses.
+
+It is single point of truth about known peers and relations of their
+overlay and underlay addresses.
+*/
+package addressbook

pkg/jsonhttp/doc.go

+// Copyright 2020 The Swarm Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package jsonhttp contains utility functions that make it easier to create
+JSON-based HTTP APIs.
+*/
+package jsonhttp

pkg/jsonhttp/jsonhttptest/doc.go

+// Copyright 2020 The Swarm Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package jsonhttptest helps with end-to-end testing of JSON-based HTTP APIs.
+
+To test specific endpoint, Request function should be called with options that
+should validate response from the server:
+
+	options := []jsonhttptest.Option{
+		jsonhttptest.WithRequestHeader("Content-Type", "text/html"),
+	}
+	jsonhttptest.Request(t, client, http.MethodGet, "/", http.StatusOk, options...)
+	// ...
+
+The HTTP request will be executed using the supplied client, and response
+checked in expected status code is returned, as well as with each configured
+option function.
+*/
+package jsonhttptest

pkg/jsonhttp/jsonhttptest/jsonhttptest.go

@@ -218,6 +218,15 @@ func WithUnmarshalJSONResponse(response interface{}) Option {
 
 // WithPutResponseBody replaces the data in the provided byte slice with the
 // data from the response body of the request in the Request function.
+//
+// Example:
+//
+//	var respBytes []byte
+//	options := []jsonhttptest.Option{
+//		jsonhttptest.WithPutResponseBody(&respBytes),
+//	}
+//	// ...
+//
 func WithPutResponseBody(b *[]byte) Option {
 	return optionFunc(func(o *options) error {
 		o.responseBody = b

pkg/keystore/file/service.go

@@ -14,10 +14,15 @@ import (
 	"github.com/ethersphere/bee/pkg/crypto"
 )
 
+// Service is the file-based keystore.Service implementation.
+//
+// Keys are stored in directory where each private key is stored in a file,
+// which is encrypted with symmetric key using some password.
 type Service struct {
 	dir string
 }
 
+// New creates new file-based keystore.Service implementation.
 func New(dir string) *Service {
 	return &Service{dir: dir}
 }

pkg/keystore/keystore.go

@@ -9,9 +9,17 @@ import (
 	"errors"
 )
 
+// ErrInvalidPassword is returned when the password for decrypting content where
+// private key is stored is not valid.
 var ErrInvalidPassword = errors.New("invalid password")
 
+// Service for managing keystore private keys.
 type Service interface {
+	// Key returns the private key for a specified name that was encrypted with
+	// the provided password. If the private key does not exists it creates
+	// a new one with a name and the password, and returns with created set
+	// to true.
 	Key(name, password string) (k *ecdsa.PrivateKey, created bool, err error)
+	// Exists returns true if the key with specified name exists.
 	Exists(name string) (bool, error)
 }

pkg/keystore/mem/service.go

@@ -15,11 +15,17 @@ import (
 
 var _ keystore.Service = (*Service)(nil)
 
+// Service is the memory-based keystore.Service implementation.
+//
+// Keys are stored in an in-memory map, where the key is the name of the private
+// key, and the value is the structure where the actual private key and
+// the password are stored.
 type Service struct {
 	m  map[string]key
 	mu sync.Mutex
 }
 
+// New creates new memory-based keystore.Service implementation.
 func New() *Service {
 	return &Service{
 		m: make(map[string]key),

pkg/keystore/test/test.go

@@ -12,6 +12,8 @@ import (
 	"github.com/ethersphere/bee/pkg/keystore"
 )
 
+// Service is a utility testing function that can be used to test
+// implementations of the keystore.Service interface.
 func Service(t *testing.T, s keystore.Service) {
 	exists, err := s.Exists("swarm")
 	if err != nil {

pkg/tracing/doc.go

+// Copyright 2020 The Swarm Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package tracing helps with the propagation of the tracing span through context
+in the system. It does this for operations contained to single node, as well as
+across nodes, by injecting special headers.
+
+To use the tracing package, a Tracer instance must be created, which contains
+functions for starting new span contexts, injecting them in other data, and
+extracting the active span them from the context.
+
+To use the tracing package a Tracer instance must be created:
+
+	tracer, tracerCloser, err := tracing.NewTracer(&tracing.Options{
+		Enabled:     true,
+		Endpoint:    "127.0.0.1:6831",
+		ServiceName: "bee",
+	})
+	if err != nil {
+		// handle error
+	}
+	defer tracerCloser.Close()
+	// ...
+
+The tracer instance contains functions for starting new span contexts, injecting
+them in other data, and extracting the active span them from the context:
+
+	span, _, ctx := tracer.StartSpanFromContext(ctx, "operation-name", nil)
+
+Once the operation is finished, the open span should be finished:
+
+	span.Finish()
+
+The tracing package also provides a function for creating a logger which will
+inject a "traceid" field entry to the log line, which helps in finding out which
+log lines belong to a specific trace.
+
+To create a logger with trace just wrap an existing logger:
+
+	logger := tracing.NewLoggerWithTraceID(ctx, s.logger)
+	// ...
+	logger.Info("some message")
+
+Which will result in following log line (if the context contains tracing
+information):
+
+	time="2015-09-07T08:48:33Z" level=info msg="some message" traceid=ed65818cc1d30c
+*/
+package tracing