Document every exported symbol and how callers use the library.

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

groups.go

@@ -33,7 +33,9 @@ func (g Groups) ocsClient() OCSClient {
 	return c
 }
 
-// UserGroups returns the Nextcloud group ids of userID, calling OCS as that user.
+// UserGroups returns the Nextcloud group ids of userID.
+// The OCS call is authenticated as userID.
+// It returns an error when the OCS call fails or the body cannot be decoded.
 func (g Groups) UserGroups(userID string) ([]string, error) {
 	ocs := g.ocsClient()
 	ocs.Cred = ocs.Cred.WithUser(userID)
@@ -45,7 +47,11 @@ func (g Groups) UserGroups(userID string) ([]string, error) {
 	return decodeUserGroups(raw)
 }
 
-// GroupMembers returns the user ids in groupID, calling OCS as the Requesting user.
+// GroupMembers returns the user ids in groupID.
+// The OCS call uses Cred as-is. Nextcloud requires that user to be an admin
+// or a subadmin of the group.
+// It returns an error when the OCS call fails or the body cannot be decoded.
+// There is no search or paging.
 func (g Groups) GroupMembers(groupID string) ([]string, error) {
 	ocs := g.ocsClient()
 	path := "cloud/groups/" + url.PathEscape(groupID)
@@ -70,7 +76,10 @@ func decodeGroupMembers(raw []byte) ([]string, error) {
 	return parsed.OCS.Data.Users, nil
 }
 
-// ListGroups returns instance group ids, calling OCS as the Requesting user.
+// ListGroups returns instance group ids.
+// The OCS call uses Cred as-is and needs an admin or subadmin.
+// It returns an error when the OCS call fails or the body cannot be decoded.
+// There is no search or paging.
 func (g Groups) ListGroups() ([]string, error) {
 	ocs := g.ocsClient()
 	raw, err := ocs.Call(http.MethodGet, "cloud/groups", nil)