Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>

credentials.go

@@ -7,9 +7,13 @@ import (
 	"strings"
 )
 
-// Credentials are what an ExApp needs to call Nextcloud as a user.
+// Credentials are what an ExApp needs to call Nextcloud as one user.
+// BaseURL is the Nextcloud instance URL. A trailing slash is tolerated by
+// callers in this package and is removed when they build a URL.
+// AppID, AppVersion, and AAVersion are sent as EX-APP-ID, EX-APP-VERSION,
+// and AA-VERSION. AppSecret and UserID form the AUTHORIZATION-APP-API token.
 type Credentials struct {
-	BaseURL    string // Nextcloud instance URL, no trailing slash
+	BaseURL    string
 	AppID      string
 	AppVersion string
 	AAVersion  string
@@ -17,7 +21,10 @@ type Credentials struct {
 	UserID     string
 }
 
-// AuthHeaders returns AppAPI auth headers for requests to Nextcloud.
+// AuthHeaders returns AppAPI headers for a request to Nextcloud.
+// The set is AA-VERSION, EX-APP-ID, EX-APP-VERSION, AUTHORIZATION-APP-API,
+// and OCS-APIRequest. AUTHORIZATION-APP-API is base64 of UserID, a colon,
+// and AppSecret. The method does not return an error; empty fields are sent as empty.
 func (c Credentials) AuthHeaders() http.Header {
 	h := make(http.Header)
 	h.Set("AA-VERSION", c.AAVersion)
@@ -29,14 +36,18 @@ func (c Credentials) AuthHeaders() http.Header {
 	return h
 }
 
-// WithUser returns a copy acting as userID.
+// WithUser returns a copy whose UserID is userID.
+// The receiver is not modified.
 func (c Credentials) WithUser(userID string) Credentials {
 	out := c
 	out.UserID = userID
 	return out
 }
 
-// UserFromRequest reads the requesting user from AUTHORIZATION-APP-API on an inbound ExApp request.
+// UserFromRequest reads the requesting user from AUTHORIZATION-APP-API
+// on an inbound ExApp request.
+// It returns an error when the header is missing, is not base64, or contains
+// no user id before the colon.
 func UserFromRequest(r *http.Request) (string, error) {
 	raw := r.Header.Get("AUTHORIZATION-APP-API")
 	if raw == "" {