add missing documentation

3 files changed, 22 insertions, 1 deletions

diff --git a/call.go b/call.go
index 227950b..dc86dac 100644
--- a/call.go
+++ b/call.go
@@ -12,16 +12,24 @@ type rpcCall struct {
 	Params any    `json:"params,omitempty"`
 }
 
+// A Call is anything that provides a method name
+// and a list of status codes that indicate basic success.
+// It can be executed through a Client.
 type Call interface {
 	method() string
 	expectedStatus() []Status
 }
 
+// A Response contains the Status of a response to a Call
+// as well as the response parameters.
+// Data is nil if there are no response parameters.
 type Response struct {
 	StatusCode Status `json:"code"`
 	Data       any    `json:"resData"`
 }
 
+// ErrUnexpectedStatus indicates that a Call was responded to
+// but the Status doesn't match any of the expected Statuses of the Call.
 type ErrUnexpectedStatus struct {
 	expected []Status
 	got      Status
@@ -32,6 +40,8 @@ func (e *ErrUnexpectedStatus) Error() string {
 	return fmt.Sprintf(format, e.expected, e.got)
 }
 
+// Call sends a Call to the API endpoint and waits for a response or an error.
+// It returns net.ErrClosed if the Client is closed.
 func (c *Client) Call(call Call) (*Response, error) {
 	wrapped := &rpcCall{
 		Method: call.method(),
diff --git a/client.go b/client.go
index b27095e..2a621ab 100644
--- a/client.go
+++ b/client.go
@@ -12,8 +12,13 @@ import (
 type Endpoint string
 
 const (
+	// Production is the JSON-RPC production endpoint.
+	// Calls can modify real zones. Only use this if you really need it.
 	Production Endpoint = "https://api.domrobot.com/jsonrpc/"
-	Sandbox             = "https://api.ote.domrobot.com/jsonrpc/"
+
+	// Sandbox is the JSON-RPC sandbox endpoint.
+	// Use this endpoint for experiments or testing of any kind.
+	Sandbox = "https://api.ote.domrobot.com/jsonrpc/"
 )
 
 const requestTimeout = 30 * time.Second
@@ -28,6 +33,11 @@ type Client struct {
 	err     error
 }
 
+// Login creates a new Client and attempts to start a session
+// with the given credentials.
+//
+// Two-factor authentication is currently not supported,
+// contributions are welcome.
 func Login(endpoint Endpoint, user, passwd string) (*Client, error) {
 	jar, err := cookiejar.New(&cookiejar.Options{})
 	if err != nil {
diff --git a/status.go b/status.go
index 257d060..b29e7ba 100644
--- a/status.go
+++ b/status.go
@@ -2,6 +2,7 @@ package inwx
 
 // A Status contains basic information
 // about whether and how a Call was processed.
+// See https://www.inwx.com/en/help/apidoc/f/ch04.html for descriptions.
 type Status int
 
 const (