Update to canonical doc

.github/workflows/check.yml

@@ -30,14 +30,8 @@ jobs:
         run: go get -t -v ./ably/...
 
       - name: Format
-        run: |
-          if go version | awk '$3 !~ /go1.18/ {exit(1)}'; 
-          then 
-            echo -n Skipping gofmt test for ;
-            go version
-            exit 0
-          fi
-          if [ "$(gofmt -l . | wc -l)" -gt 0 ]; then exit 1; fi
+        if: matrix.go-version != '1.18'
+        run: if [ "$(gofmt -l . | wc -l)" -gt 0 ]; then exit 1; fi
 
       - name: Vet
         run: go vet ./ably/... ./scripts/...

CONTRIBUTING.md

@@ -11,6 +11,27 @@ Because this package uses `internal` packages, all fork development has to happe
 7. push to the branch: `git push fork my-new-feature`
 8. create a new Pull Request.
 
+### Previewing Godoc Locally
+
+1. Install [godoc](https://pkg.go.dev/golang.org/x/tools/cmd/godoc) globally via `go get` and run at root
+
+```bash
+  godoc -http=:8000
+```
+- Open the link http://localhost:8000/ for viewing the documentation.
+
+2. Export `godoc` using latest version of [gopages](https://pkg.go.dev/github.com/johnstarich/go/gopages#section-readme)
+```bash
+  gopages -brand-description "Go client library for Ably realtime messaging service." -brand-title "Ably Go SDK"
+```
+- `godoc html` is exported to `dist` and can be served using `python3 http.server`
+
+```bash
+  cd dist
+  py -m http.server 8000
+```
+- Open the link http://localhost:8000/ for viewing the documentation.
+
 ### Running Tests
 
 This project contains two types of test. Test which use the `ablytest` package and tests which dont. 

ably/auth.go

@@ -58,22 +58,35 @@ func addHeaders(lhs, rhs http.Header) http.Header {
 	return lhs
 }
 
-// Auth
+// Auth creates Ably [ably.TokenRequest] objects and obtains Ably Tokens from Ably to
+// subsequently issue to less trusted clients.
 type Auth struct {
-	mtx      sync.Mutex
-	method   int
-	client   *REST
-	params   *TokenParams // save params to use with token renewal
-	host     string       // a host part of AuthURL
-	clientID string       // clientID of the authenticated user or wildcard "*"
+	mtx sync.Mutex
+
+	method int
+	client *REST
+
+	// params to use with token renewal
+	params *TokenParams
+
+	// host part of AuthURL
+	host string
+
+	// clientID is used for identifying this client when publishing messages or for presence purposes.
+	// The clientId can be any non-empty string, except it cannot contain a *.
+	// This option is primarily intended to be used in situations where the library is instantiated with a key.
+	// Note that a clientId may also be implicit in a token used to instantiate the library.
+	// An error is raised if a clientId specified here conflicts with the clientId implicit in the token.
+	// Find out more about identified clients (RSA7, RSC17, RSA12).
+	clientID string
 
 	// onExplicitAuthorize is the callback that Realtime sets to reauthorize with the
 	// server when Authorize is explicitly called.
 	onExplicitAuthorize func(context.Context, *TokenDetails)
 
 	serverTimeOffset time.Duration
 
-	// ServerTimeHandler when provided this will be used to query server time.
+	// serverTimeHandler when provided this will be used to query server time.
 	serverTimeHandler func() (time.Time, error)
 }
 
@@ -109,7 +122,13 @@ func newAuth(client *REST) (*Auth, error) {
 	return a, nil
 }
 
-// ClientID
+// ClientID method returns clientId if not a wildcard string (*), otherwise returns an empty string.
+// It is used for identifying this client when publishing messages or for presence purposes.
+// The clientId can be any non-empty string, except it cannot contain a *.
+// This option is primarily intended to be used in situations where the library is instantiated with a key.
+// Note that a clientId may also be implicit in a token used to instantiate the library.
+// An error is raised if a clientId specified here conflicts with the clientId implicit in the token.
+// Find out more about identified clients (RSA7, RSC17, RSA12).
 func (a *Auth) ClientID() string {
 	a.mtx.Lock()
 	defer a.mtx.Unlock()
@@ -135,7 +154,18 @@ func (a *Auth) updateClientID(clientID string) {
 	a.clientID = clientID
 }
 
-// CreateTokenRequest
+// CreateTokenRequest creates and signs an Ably [ably.TokenRequest] based on the specified
+// (or if none specified, the client library stored) [ably.TokenParams] and [ably.AuthOption].
+// Note this can only be used when the API key value is available locally.
+// Otherwise, the Ably [ably.TokenRequest] must be obtained from the key owner.
+// Use this to generate an Ably [ably.TokenRequest] in order to implement an Ably Token request callback for use by other clients.
+// Both [ably.TokenParams] and [ably.AuthOption] are optional.
+// When omitted or null, the default token parameters and authentication options for the client library are used,
+// as specified in the [ably.ClientOption] when the client library was instantiated,
+// or later updated with an explicit authorize request.
+// Values passed in are used instead of, rather than being merged with, the default values.
+// To understand why an Ably [ably.TokenRequest] may be issued to clients in favor of a token,
+// see Token Authentication explained (RSA9).
 func (a *Auth) CreateTokenRequest(params *TokenParams, opts ...AuthOption) (*TokenRequest, error) {
 	a.mtx.Lock()
 	defer a.mtx.Unlock()
@@ -169,7 +199,13 @@ func (a *Auth) createTokenRequest(params *TokenParams, opts *authOptions) (*Toke
 	return req, nil
 }
 
-// RequestToken
+// RequestToken Calls the requestToken REST API endpoint to obtain an Ably Token according to the specified
+// [ably.TokenParams] and [ably.AuthOption]. Both [ably.TokenParams] and [ably.AuthOption] are optional.
+// When omitted or null, the default token parameters and authentication options for the client library are used,
+// as specified in the [ably.ClientOption] when the client library was instantiated, or later updated with
+// an explicit authorize request. Values passed in are used instead of, rather than being merged with,
+// the default values. To understand why an Ably [ably.TokenRequest] may be issued to clients in
+// favor of a token, see Token Authentication explained (RSA8e).
 func (a *Auth) RequestToken(ctx context.Context, params *TokenParams, opts ...AuthOption) (*TokenDetails, error) {
 	a.mtx.Lock()
 	defer a.mtx.Unlock()
@@ -260,10 +296,13 @@ func (a *Auth) requestToken(ctx context.Context, params *TokenParams, opts *auth
 	return tok, tokReqClientID, nil
 }
 
-// Authorize performs authorization with ably service and returns the
-// authorization token details.
-//
-// Refers to RSA10
+// Authorize instructs the library to get a new authorized token immediately from ably server.
+// When using the realtime client, it upgrades the current realtime connection to use the new token,
+// or if not connected, initiates a connection to Ably, once the new token has been obtained.
+// Also stores any [ably.TokenParams] and [ably.AuthOption] passed in as the new defaults,
+// to be used for all subsequent implicit or explicit token requests. Any [ably.TokenParams] and
+// [ably.AuthOption] objects passed in entirely replace, as opposed to being merged with,
+// the current client library saved values (RSA10).
 func (a *Auth) Authorize(ctx context.Context, params *TokenParams, setOpts ...AuthOption) (*TokenDetails, error) {
 	var opts *authOptions
 	if setOpts != nil {
@@ -360,7 +399,7 @@ func (a *Auth) setDefaults(opts *authOptions, req *TokenRequest) error {
 	return nil
 }
 
-// Timestamp returns the timestamp to be used in authorization request.
+// timestamp returns the timestamp to be used in authorization request.
 func (a *Auth) timestamp(ctx context.Context, query bool) (time.Time, error) {
 	now := a.client.opts.Now()
 	if !query {

ably/crypto.go

@@ -7,13 +7,19 @@ import (
 	"io"
 )
 
+// Crypto contains the properties required to configure the encryption of [ably.Message] payloads.
 var Crypto struct {
-	// GenerateRandomKey returns a random key. keyLength is optional; if
-	// non-zero, it should be in bits.
+
+	// GenerateRandomKey returns a random key (as a binary/a byte array) to be used in the encryption of the channel.
+	// If the language cryptographic randomness primitives are blocking or async, a callback is used.
+	// The callback returns a generated binary key.
+	// keyLength is passed as a param. It is a length of the key, in bits, to be generated.
+	// If not specified, this is equal to the default keyLength of the default algorithm:
+	// for AES this is 256 bits (RSE2).
 	GenerateRandomKey func(keyLength int) ([]byte, error)
 
-	// GetDefaultParams returns the provided CipherParams with missing fields
-	// set to default values. The Key field must be provided.
+	// GetDefaultParams returns a [ably.CipherParams] object, using the default values for any fields
+	// not supplied by the [ably.CipherParamOptions] object. The Key field must be provided (RSE1).
 	GetDefaultParams func(CipherParams) CipherParams
 }
 

ably/doc.go

@@ -1,8 +1,16 @@
-// Package ably is the official Ably client library for Go.
+// Package ably
+//
+// # Ably Go Client Library SDK API Reference
+//
+// The Go Client Library SDK supports a realtime and a REST interface. The Go API references are generated from the [Ably Go Client Library SDK source code] using [godoc] and structured by classes.
+//
+// The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels. The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics, token authentication and publishing to a channel.
+//
+// View the [Ably docs] for conceptual information on using Ably, and for API references featuring all languages. The combined [API references] are organized by features and split between the [realtime] and [REST] interfaces.
 //
 // Get started at https://github.com/ably/ably-go#using-the-realtime-api.
 //
-// Event Emitters
+// # Event Emitters
 //
 // An event emitter pattern appears in multiple places in the library.
 //
@@ -37,7 +45,7 @@
 // For messages and presence messages, "on" is called "subscribe" and "off" is
 // called "unsubscribe".
 //
-// Paginated results
+// # Paginated results
 //
 // Most requests to the Ably REST API return a single page of results, with
 // hyperlinks to the first and next pages in the whole collection of results.
@@ -58,7 +66,7 @@
 // from the iterator object. Finally, once it returns false, the Err method must
 // be called to check if the iterator stopped due to some error, or else, it
 // just finished going through all pages.
-
+//
 // Calling the First method on the PaginatedResults returns the first page of the
 // results. However, the Next method has to be called before inspecting the items.
 //
@@ -67,4 +75,11 @@
 // last page. Both methods return a true or false value.
 //
 // See the PaginatedResults example.
+//
+// [Ably Go Client Library SDK source code]: https://github.com/ably/ably-go/
+// [godoc]: https://pkg.go.dev/golang.org/x/tools/cmd/godoc
+// [Ably docs]: https://ably.com/docs/
+// [API references]: https://ably.com/docs/api/
+// [realtime]: https://ably.com/docs/api/realtime-sdk?lang=go
+// [REST]: https://ably.com/docs/api/rest-sdk?lang=go
 package ably

ably/error.go

@@ -40,15 +40,19 @@ func codeFromStatus(statusCode int) ErrorCode {
 	}
 }
 
-// ErrorInfo describes error returned from Ably API. It always has non-zero error
-// code. It may contain underlying error value which caused the failure
-// condition.
+// ErrorInfo is a generic Ably error object that contains an Ably-specific status code, and a generic status code.
+// Errors returned from the Ably server are compatible with the ErrorInfo structure and should result in errors
+// that inherit from ErrorInfo. It may contain underlying error value which caused the failure.
 type ErrorInfo struct {
+	// StatusCode is a http Status code corresponding to this error, where applicable (TI1).
 	StatusCode int
-	Code       ErrorCode
-	HRef       string
-	Cause      *ErrorInfo
-
+	// Code is the standard [ably error code]
+	// [ably error code]: https://github.com/ably/ably-common/blob/main/protocol/errors.json (TI1).
+	Code ErrorCode
+	// HRef is included for REST responses to provide a URL for additional help on the error code (TI4).
+	HRef string
+	// Cause provides Information pertaining to what caused the error where available (TI1).
+	Cause *ErrorInfo
 	// err is the application-level error we're wrapping, or just a message.
 	// If Cause is non-nil, err == *Cause.
 	err error
@@ -66,7 +70,6 @@ func (e ErrorInfo) Error() string {
 		see = " See " + errorHref
 	}
 	return fmt.Sprintf("[ErrorInfo :%s code=%d %[2]v statusCode=%d]%s", msg, e.Code, e.StatusCode, see)
-
 }
 
 // Unwrap implements the implicit interface that errors.Unwrap understands.

ably/event_emitter.go

@@ -5,6 +5,9 @@ import (
 	"sync"
 )
 
+// eventEmitter is a generic interface for event registration and delivery used
+// in a number of the types in the Realtime client library. For example, the
+// [ably.Connection] object emits events for connection state using the EventEmitter pattern.
 type eventEmitter struct {
 	sync.Mutex
 	listeners listenersForEvent
@@ -90,26 +93,38 @@ func newEventEmitter(log logger) *eventEmitter {
 	}
 }
 
-// On registers an event listener. The event must be comparable to the
-// eventEmitter's event type, and only events equal to it will trigger the
-// listener.
-//
-// It returns a function to deregister the listener.
+// On registers the provided listener for the specified event.
+// If on() is called more than once with the same listener and event, the listener is added multiple times
+// to its listener registry. Therefore, as an example, assuming the same listener is registered twice using on(),
+// and an event is emitted once, the listener would be invoked twice.
+// It returns a function to deregister the listener (RTE4).
 func (em *eventEmitter) On(event emitterEvent, handle func(emitterData)) (off func()) {
 	return em.on(event, handle, false)
 }
 
-// OnAll is like On, except the listener is triggered by all events.
+// OnAll registers the provided listener for all events.
+// If on() is called more than once with the same listener and event, the listener is added multiple times to
+// its listener registry. Therefore, as an example, assuming the same listener is registered twice using on(),
+// and an event is emitted once, the listener would be invoked twice (RTE4).
 func (em *eventEmitter) OnAll(handle func(emitterData)) (off func()) {
 	return em.on(nil, handle, false)
 }
 
-// Once is like On, except the listener is deregistered once first triggered.
+// Once is like On, except the listener is de-registered once first triggered.
+// Registers the provided listener for the first occurrence of a single named event specified as the Event argument.
+// If once() is called more than once with the same listener, the listener is added multiple times
+// to its listener registry. Therefore, as an example, assuming the same listener is registered twice using once(),
+// and an event is emitted once, the listener would be invoked twice. However, all subsequent events emitted
+// would not invoke the listener as once() ensures that each registration is only invoked once (RTE4).
 func (em *eventEmitter) Once(event emitterEvent, handle func(emitterData)) (off func()) {
 	return em.on(event, handle, true)
 }
 
-// OnceAll is like Once, except the listener is triggered by all events.
+// OnceAll registers the provided listener for the first event that is emitted.
+// If once() is called more than once with the same listener, the listener is added multiple times to
+// its listener registry. Therefore, as an example, assuming the same listener is registered twice using once(),
+// and an event is emitted once, the listener would be invoked twice. However, all subsequent events emitted
+// would not invoke the listener as once() ensures that each registration is only invoked once (RTE4).
 func (em *eventEmitter) OnceAll(handle func(emitterData)) (off func()) {
 	return em.on(nil, handle, true)
 }
@@ -142,14 +157,12 @@ func (em *eventEmitter) on(event emitterEvent, handle func(emitterData), once bo
 	}
 }
 
-// Off deregisters event listeners. The event must be comparable to the
-// eventEmitter's event type, and only listeners that were associated with that
-// event will be removed.
+// Off removes all listeners matching the given event.
 func (em *eventEmitter) Off(event emitterEvent) {
 	em.off(event)
 }
 
-// OffAll is like Off, except is deregisters all event listeners.
+// OffAll de-registers all registrations, for all events and listeners.
 func (em *eventEmitter) OffAll() {
 	em.off(nil)
 }
@@ -167,6 +180,9 @@ func (em *eventEmitter) off(event emitterEvent) {
 	}
 }
 
+// Emit sends an event, calling registered listeners with the given event name and any other given arguments.
+// If an exception is raised in any of the listeners, the exception is caught by the EventEmitter
+// and the exception is logged to the Ably logger (RTE6).
 func (em *eventEmitter) Emit(event emitterEvent, data emitterData) {
 	// Let's first collect the handlers, and then call them outside the lock.
 	// This allows the handler functions to call again into the event emitter,

ably/internal/ablyutil/merge.go

@@ -2,7 +2,7 @@ package ablyutil
 
 import "reflect"
 
-// merge iterates over fields of struct pointed by v and when it's non-zero,
+// Merge iterates over fields of struct pointed by v and when it's non-zero,
 // copies its value to corresponding filed in orig.
 //
 // merge assumes both orig and v are pointers to a struct value of the

ably/logger.go

@@ -57,8 +57,7 @@ func (s *stdLogger) Printf(level LogLevel, format string, v ...interface{}) {
 	s.Logger.Printf(fmt.Sprintf("[%s] %s", level, format), v...)
 }
 
-// logger is the internal logger type, with helper methods that wrap the raw
-// Logger interface.
+// logger is the internal logger type, with helper methods that wrap the raw Logger interface.
 type logger struct {
 	l Logger
 }