From 7a5b623a834ab8f82227d279e7a7a9fb66b269f7 Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Thu, 2 Oct 2025 15:59:38 +0200 Subject: [PATCH] Docs: Improve code comments in internal/entity/album*.go Signed-off-by: Michael Mayer --- internal/entity/album.go | 29 +++++++++++++++-------------- internal/entity/album_cache.go | 4 ++-- internal/entity/album_user.go | 8 ++++---- 3 files changed, 21 insertions(+), 20 deletions(-) diff --git a/internal/entity/album.go b/internal/entity/album.go index 526c7f8e7..aa630b77d 100644 --- a/internal/entity/album.go +++ b/internal/entity/album.go @@ -39,9 +39,10 @@ var ( var albumMutex = sync.Mutex{} +// Albums is a helper slice type for working with groups of albums. type Albums []Album -// Album represents a photo album +// Album represents a photo album and its metadata, including filter definitions for virtual albums. type Album struct { ID uint `gorm:"primary_key" json:"ID" yaml:"-"` AlbumUID string `gorm:"type:VARBINARY(42);unique_index;" json:"UID" yaml:"UID"` @@ -92,7 +93,7 @@ func (Album) TableName() string { return "albums" } -// UpdateAlbum updates album attributes in the database. +// UpdateAlbum updates album attributes directly in the database by UID. func UpdateAlbum(albumUID string, values interface{}) (err error) { if rnd.InvalidUID(albumUID, AlbumUID) { return fmt.Errorf("album: invalid uid %s", clean.Log(albumUID)) @@ -103,12 +104,12 @@ func UpdateAlbum(albumUID string, values interface{}) (err error) { return nil } -// AddPhotoToAlbums adds a photo UID to multiple albums and automatically creates them if needed. +// AddPhotoToAlbums adds a photo UID to multiple albums and automatically creates them with default ownership when required. func AddPhotoToAlbums(uid string, albums []string) (err error) { return AddPhotoToUserAlbums(uid, albums, DefaultOrderAlbum, OwnerUnknown) } -// AddPhotoToUserAlbums adds a photo UID to multiple albums and automatically creates them as a user if needed. +// AddPhotoToUserAlbums adds a photo UID to multiple albums while creating any missing albums for the given user. func AddPhotoToUserAlbums(photoUid string, albums []string, sortOrder, userUid string) (err error) { if photoUid == "" || len(albums) == 0 { // Do nothing. @@ -159,12 +160,12 @@ func AddPhotoToUserAlbums(photoUid string, albums []string, sortOrder, userUid s return err } -// NewAlbum creates a new album of the given type. +// NewAlbum creates a new album of the given type using default ownership. func NewAlbum(albumTitle, albumType string) *Album { return NewUserAlbum(albumTitle, albumType, sortby.Oldest, OwnerUnknown) } -// NewUserAlbum creates a new album owned by a user. +// NewUserAlbum creates a new album owned by a user and pre-fills timestamps/order defaults. func NewUserAlbum(albumTitle, albumType, sortOrder, userUid string) *Album { now := Now() @@ -193,7 +194,7 @@ func NewUserAlbum(albumTitle, albumType, sortOrder, userUid string) *Album { return result } -// NewFolderAlbum creates a new folder album. +// NewFolderAlbum creates a new album representing a filesystem folder. func NewFolderAlbum(albumTitle, albumPath, albumFilter string) *Album { albumSlug := txt.Slug(albumPath) @@ -218,7 +219,7 @@ func NewFolderAlbum(albumTitle, albumPath, albumFilter string) *Album { return result } -// NewMomentsAlbum creates a new moment. +// NewMomentsAlbum creates a new automatically generated moment album. func NewMomentsAlbum(albumTitle, albumSlug, albumFilter string) *Album { if albumTitle == "" || albumSlug == "" || albumFilter == "" { return nil @@ -240,7 +241,7 @@ func NewMomentsAlbum(albumTitle, albumSlug, albumFilter string) *Album { return result } -// NewStateAlbum creates a new moment. +// NewStateAlbum creates an automatically generated album for a specific state or region. func NewStateAlbum(albumTitle, albumSlug, albumFilter string) *Album { albumTitle = strings.TrimSpace(albumTitle) albumSlug = strings.TrimSpace(albumSlug) @@ -265,7 +266,7 @@ func NewStateAlbum(albumTitle, albumSlug, albumFilter string) *Album { return result } -// NewMonthAlbum creates a new month album. +// NewMonthAlbum creates an automatically generated album for a specific month. func NewMonthAlbum(albumTitle, albumSlug string, year, month int) *Album { albumTitle = strings.TrimSpace(albumTitle) albumSlug = strings.TrimSpace(albumSlug) @@ -298,7 +299,7 @@ func NewMonthAlbum(albumTitle, albumSlug string, year, month int) *Album { return result } -// FindMonthAlbum finds a matching month album or returns nil. +// FindMonthAlbum returns the matching month album or nil if none exists. func FindMonthAlbum(year, month int) *Album { m := Album{} @@ -313,7 +314,7 @@ func FindMonthAlbum(year, month int) *Album { return &m } -// FindAlbumBySlug finds a matching album or returns nil. +// FindAlbumBySlug returns the album with the given slug/type combination. func FindAlbumBySlug(albumSlug, albumType string) *Album { m := Album{} @@ -328,7 +329,7 @@ func FindAlbumBySlug(albumSlug, albumType string) *Album { return &m } -// FindAlbumByAttr finds an album by filters and slugs, or returns nil. +// FindAlbumByAttr returns an album matching any of the provided slugs or filters. func FindAlbumByAttr(slugs, filters []string, albumType string) *Album { m := Album{} @@ -355,7 +356,7 @@ func FindAlbumByAttr(slugs, filters []string, albumType string) *Album { return &m } -// FindFolderAlbum finds a matching folder album or returns nil. +// FindFolderAlbum looks up a folder album by its canonical path or slug. func FindFolderAlbum(albumPath string) *Album { albumPath = strings.Trim(albumPath, string(os.PathSeparator)) albumSlug := txt.Slug(albumPath) diff --git a/internal/entity/album_cache.go b/internal/entity/album_cache.go index 2e7ff136b..ee663d528 100644 --- a/internal/entity/album_cache.go +++ b/internal/entity/album_cache.go @@ -12,12 +12,12 @@ import ( var albumCache = gc.New(15*time.Minute, 15*time.Minute) -// FlushAlbumCache resets the album cache. +// FlushAlbumCache clears any cached album entries. func FlushAlbumCache() { albumCache.Flush() } -// CachedAlbumByUID returns an existing album or an error if not found. +// CachedAlbumByUID returns the album with the specified UID from cache or database. func CachedAlbumByUID(uid string) (m Album, err error) { // Valid album UID? if uid == "" || rnd.InvalidUID(uid, AlbumUID) { diff --git a/internal/entity/album_user.go b/internal/entity/album_user.go index a66bd78b2..13a4ac200 100644 --- a/internal/entity/album_user.go +++ b/internal/entity/album_user.go @@ -2,7 +2,7 @@ package entity import "github.com/photoprism/photoprism/internal/event" -// AlbumUser represents the user and group ownership of an Album and the corresponding permissions. +// AlbumUser maps an album to a user or team and stores the associated permissions. type AlbumUser struct { UID string `gorm:"type:VARBINARY(42);primary_key;auto_increment:false" json:"UID" yaml:"UID"` UserUID string `gorm:"type:VARBINARY(42);primary_key;auto_increment:false;index" json:"UserUID,omitempty" yaml:"UserUID,omitempty"` @@ -15,7 +15,7 @@ func (AlbumUser) TableName() string { return "albums_users" } -// NewAlbumUser creates a new entity model. +// NewAlbumUser creates a new ownership/permission entry for an album. func NewAlbumUser(uid, userUid, teamUid string, perm uint) *AlbumUser { result := &AlbumUser{ UID: uid, @@ -32,12 +32,12 @@ func (m *AlbumUser) Create() error { return Db().Create(m).Error } -// Save updates the record in the database or inserts a new record if it does not already exist. +// Save updates the record or inserts it when no row exists yet. func (m *AlbumUser) Save() error { return Db().Save(m).Error } -// FirstOrCreateAlbumUser returns the existing record or inserts a new record if it does not already exist. +// FirstOrCreateAlbumUser returns the existing record or inserts it when missing, auditing failures. func FirstOrCreateAlbumUser(m *AlbumUser) *AlbumUser { found := AlbumUser{}