Docs: Improve code comments in internal/entity/auth*.go

Signed-off-by: Michael Mayer <michael@photoprism.app>

internal/entity/auth_client.go

@@ -25,10 +25,10 @@ const (
 	ClientUID = byte('c')
 )
 
-// Clients represents a list of client applications.
+// Clients is a convenience alias for slices of Client.
 type Clients []Client
 
-// Client represents a client application.
+// Client represents an OAuth/OpenID client registered with PhotoPrism.
 type Client struct {
 	ClientUID    string          `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;" json:"-" yaml:"ClientUID"`
 	NodeUUID     string          `gorm:"type:VARBINARY(64);index;default:'';" json:"NodeUUID,omitempty" yaml:"NodeUUID,omitempty"`
@@ -60,7 +60,7 @@ func (Client) TableName() string {
 	return "auth_clients"
 }
 
-// NewClient returns a new client application instance.
+// NewClient returns a new client application instance with default ACL role and authentication settings.
 func NewClient() *Client {
 	return &Client{
 		UserUID:      "",

internal/entity/auth_session.go

@@ -30,10 +30,10 @@ const (
 	UnknownIP     = limiter.DefaultIP
 )
 
-// Sessions represents a list of sessions.
+// Sessions is a convenience alias for slices of Session.
 type Sessions []Session
 
-// Session represents a User session.
+// Session represents an authenticated user or client session persisted in the database.
 type Session struct {
 	ID            string          `gorm:"type:VARBINARY(2048);primary_key;auto_increment:false;" json:"-" yaml:"ID"`
 	authToken     string          `gorm:"-" yaml:"-"`

internal/entity/auth_session_delete.go

@@ -11,7 +11,7 @@ import (
 	"github.com/photoprism/photoprism/pkg/time/unix"
 )
 
-// DeleteSession permanently deletes a session.
+// DeleteSession permanently deletes the session and any sessions that were derived from it.
 func DeleteSession(s *Session) error {
 	if s == nil {
 		return nil
@@ -38,7 +38,7 @@ func DeleteSession(s *Session) error {
 	return UnscopedDb().Delete(s).Error
 }
 
-// DeleteChildSessions deletes any other sessions that were authenticated with the specified session.
+// DeleteChildSessions deletes sessions that authenticated via the provided parent session ID.
 func DeleteChildSessions(s *Session) (deleted int) {
 	if s == nil {
 		return 0
@@ -64,7 +64,7 @@ func DeleteChildSessions(s *Session) (deleted int) {
 	return deleted
 }
 
-// DeleteClientSessions deletes client sessions above the specified limit.
+// DeleteClientSessions deletes sessions for the client beyond the configured retention limit.
 func DeleteClientSessions(client *Client, authMethod authn.MethodType, limit int64) (deleted int) {
 	if limit < 0 {
 		return 0
@@ -110,7 +110,7 @@ func DeleteClientSessions(client *Client, authMethod authn.MethodType, limit int
 	return deleted
 }
 
-// DeleteExpiredSessions deletes all expired sessions.
+// DeleteExpiredSessions removes sessions whose expiration timestamp has passed.
 func DeleteExpiredSessions() (deleted int) {
 	found := Sessions{}
 

internal/entity/auth_session_login.go

@@ -18,7 +18,7 @@ import (
 	"github.com/photoprism/photoprism/pkg/txt"
 )
 
-// Auth checks if the credentials are valid and returns the user and authentication provider.
+// Auth validates login credentials and returns the authenticated user plus provider/method metadata.
 var Auth = func(frm form.Login, s *Session, c *gin.Context) (user *User, provider authn.ProviderType, method authn.MethodType, err error) {
 	// Get sanitized username from login form.
 	nameName := frm.CleanUsername()
@@ -39,7 +39,7 @@ var Auth = func(frm form.Login, s *Session, c *gin.Context) (user *User, provide
 	return user, provider, method, err
 }
 
-// AuthSession returns the client session that belongs to the auth token provided, or returns nil if it was not found.
+// AuthSession resolves an existing session from an app password token embedded in the login form.
 func AuthSession(frm form.Login, c *gin.Context) (sess *Session, user *User, err error) {
 	if frm.Password == "" {
 		// Abort authentication if no token was provided.
@@ -68,7 +68,7 @@ func AuthSession(frm form.Login, c *gin.Context) (sess *Session, user *User, err
 	return sess, sess.GetUser(), nil
 }
 
-// AuthLocal authenticates against the local user database with the specified username and password.
+// AuthLocal authenticates against the local user database, handling OTP and app-password flows.
 func AuthLocal(user *User, frm form.Login, s *Session, c *gin.Context) (provider authn.ProviderType, method authn.MethodType, err error) {
 	// Set defaults.
 	provider = authn.ProviderNone

internal/entity/auth_tokens.go

@@ -4,6 +4,7 @@ import (
 	"github.com/photoprism/photoprism/pkg/rnd"
 )
 
+// Reserved token names used for configuration and public access.
 const TokenConfig = "__config__"
 const TokenPublic = "public"
 
@@ -11,7 +12,7 @@ var PreviewToken = NewStringMap(Strings{})
 var DownloadToken = NewStringMap(Strings{})
 var ValidateTokens = true
 
-// GenerateToken returns a random string token.
+// GenerateToken returns a short random token for previews or downloads.
 func GenerateToken() string {
 	return rnd.Base36(8)
 }

internal/entity/auth_user.go

@@ -40,10 +40,10 @@ var PasswordLength = PasswordLengthDefault
 // UsersPath is the relative path for user assets.
 var UsersPath = "users"
 
-// Users represents a list of users.
+// Users is a convenience alias for slices of User.
 type Users []User
 
-// User represents a person that may optionally log in as user.
+// User represents an account that can authenticate with PhotoPrism.
 type User struct {
 	ID            int           `gorm:"primary_key" json:"ID" yaml:"-"`
 	UUID          string        `gorm:"type:VARBINARY(64);column:user_uuid;index;" json:"UUID,omitempty" yaml:"UUID,omitempty"`

internal/entity/auth_user_cli.go

@@ -8,7 +8,7 @@ import (
 	"github.com/photoprism/photoprism/pkg/clean"
 )
 
-// SetValuesFromCli updates the entity values from a CLI context and validates them.
+// SetValuesFromCli updates user fields based on CLI flags and invalidates sessions after privilege changes.
 func (m *User) SetValuesFromCli(ctx *cli.Context) error {
 	frm := form.NewUserFromCli(ctx)
 
@@ -102,7 +102,7 @@ func (m *User) SetValuesFromCli(ctx *cli.Context) error {
 	return nil
 }
 
-// RestoreFromCli restored the account from a CLI context.
+// RestoreFromCli restores a deleted account from CLI input and optionally sets a new password.
 func (m *User) RestoreFromCli(ctx *cli.Context, newPassword string) (err error) {
 	m.DeletedAt = nil
 

internal/entity/auth_user_default.go

@@ -6,7 +6,7 @@ import (
 	"github.com/photoprism/photoprism/pkg/authn"
 )
 
-// Role defaults.
+// Role defaults referenced when creating built-in users.
 const (
 	AdminUserName      = "admin"
 	AdminDisplayName   = "Admin"

internal/entity/auth_user_details.go

@@ -15,7 +15,7 @@ const (
 	GenderOther  = "other"
 )
 
-// UserDetails represents user profile information.
+// UserDetails stores extended profile information for a user account.
 type UserDetails struct {
 	UserUID      string    `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;" json:"-" yaml:"-"`
 	SubjUID      string    `gorm:"type:VARBINARY(42);index;" json:"SubjUID,omitempty" yaml:"SubjUID,omitempty"`
@@ -58,12 +58,12 @@ func (UserDetails) TableName() string {
 	return "auth_users_details"
 }
 
-// NewUserDetails creates new user details.
+// NewUserDetails allocates an empty profile record for the user UID.
 func NewUserDetails(uid string) *UserDetails {
 	return &UserDetails{UserUID: uid}
 }
 
-// CreateUserDetails creates new user details or returns nil on error.
+// CreateUserDetails ensures a profile record exists for the user, creating one when absent.
 func CreateUserDetails(user *User) error {
 	if user == nil {
 		return fmt.Errorf("user is nil")

internal/entity/auth_user_settings.go

@@ -9,7 +9,7 @@ import (
 	"github.com/photoprism/photoprism/pkg/rnd"
 )
 
-// UserSettings represents user preferences.
+// UserSettings stores per-user UI, indexing, and workflow preferences.
 type UserSettings struct {
 	UserUID              string    `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;" json:"-" yaml:"UserUID"`
 	UITheme              string    `gorm:"type:VARBINARY(32);column:ui_theme;" json:"UITheme,omitempty" yaml:"UITheme,omitempty"`
@@ -38,12 +38,12 @@ func (UserSettings) TableName() string {
 	return "auth_users_settings"
 }
 
-// NewUserSettings creates new user preferences.
+// NewUserSettings allocates a settings record bound to the provided user UID.
 func NewUserSettings(uid string) *UserSettings {
 	return &UserSettings{UserUID: uid}
 }
 
-// CreateUserSettings creates new user settings or returns nil on error.
+// CreateUserSettings ensures settings exist for the given user, creating them if missing.
 func CreateUserSettings(user *User) error {
 	if user == nil {
 		return fmt.Errorf("user is nil")

internal/entity/auth_user_share.go

@@ -27,7 +27,7 @@ const (
 	SharePrefix = "share"
 )
 
-// UserShares represents shared content.
+// UserShares groups share relationships granted to a user.
 type UserShares []UserShare
 
 // UIDs returns shared UIDs.
@@ -61,7 +61,7 @@ func (m UserShares) Contains(uid string) bool {
 	return false
 }
 
-// UserShare represents content shared with a user.
+// UserShare represents a share relationship granting a user access to another entity.
 type UserShare struct {
 	UserUID   string     `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;" json:"-" yaml:"UserUID"`
 	ShareUID  string     `gorm:"type:VARBINARY(42);primary_key;index;" json:"ShareUID" yaml:"ShareUID"`
@@ -79,7 +79,7 @@ func (UserShare) TableName() string {
 	return "auth_users_shares"
 }
 
-// NewUserShare creates a new entity model.
+// NewUserShare constructs a share relationship with optional expiration.
 func NewUserShare(userUID, shareUid string, perm uint, expires *time.Time) *UserShare {
 	result := &UserShare{
 		UserUID:   userUID,