feat: add comments and cleanup unused imports across codebase

api/watchlist/handler.go

@@ -19,6 +19,7 @@ func NewHandler(service *Service) *Handler {
 	return &Handler{service: service}
 }
 
+// HandleUpdateWatchlist adds or updates anime in user's watchlist. accepts json {animeId, status}.
 func (h *Handler) HandleUpdateWatchlist(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
@@ -40,6 +41,7 @@ func (h *Handler) HandleUpdateWatchlist(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
+	// default status if not provided
 	if body.Status == "" {
 		body.Status = "plan_to_watch"
 	}
@@ -53,6 +55,7 @@ func (h *Handler) HandleUpdateWatchlist(w http.ResponseWriter, r *http.Request)
 	w.WriteHeader(http.StatusOK)
 }
 
+// HandleDeleteWatchlist removes anime from user's watchlist. expects /api/watchlist/{animeId}.
 func (h *Handler) HandleDeleteWatchlist(w http.ResponseWriter, r *http.Request) {
 	user := middleware.GetUser(r.Context())
 	if user == nil {
@@ -73,10 +76,12 @@ func (h *Handler) HandleDeleteWatchlist(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
+	// htmx: redirect to watchlist page after delete
 	w.Header().Set("HX-Redirect", "/watchlist")
 	w.WriteHeader(http.StatusOK)
 }
 
+// HandleDeleteContinueWatching removes entry from user's continue watching. expects /api/continue-watching/{animeId}.
 func (h *Handler) HandleDeleteContinueWatching(w http.ResponseWriter, r *http.Request) {
 	user := middleware.GetUser(r.Context())
 	if user == nil {
@@ -101,6 +106,7 @@ func (h *Handler) HandleDeleteContinueWatching(w http.ResponseWriter, r *http.Re
 	w.WriteHeader(http.StatusOK)
 }
 
+// HandleGetWatchlist renders user's watchlist page, grouped by status.
 func (h *Handler) HandleGetWatchlist(w http.ResponseWriter, r *http.Request) {
 	user := middleware.GetUser(r.Context())
 	if user == nil {
@@ -119,6 +125,7 @@ func (h *Handler) HandleGetWatchlist(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// group entries by status for display
 	watchlistByStatus := make(map[string][]db.GetUserWatchListRow)
 	allEntries := make([]db.GetUserWatchListRow, 0)
 	watchlistIDs := make([]int64, len(entries))
@@ -149,6 +156,7 @@ func (h *Handler) HandleGetWatchlist(w http.ResponseWriter, r *http.Request) {
 		},
 	}
 
+	// use partial template for htmx requests
 	templateName := "watchlist.gohtml"
 	if r.Header.Get("HX-Request") == "true" {
 		templateName = "watchlist_partial.gohtml"

api/watchlist/service.go

@@ -36,12 +36,14 @@ func NewService(db db.Querier, sqlDB *sql.DB, jikanClient *jikan.Client) *Servic
 	return &Service{db: db, sqlDB: sqlDB, jikanClient: jikanClient}
 }
 
+// ensureAnimeExists checks if anime exists in db, fetches from jikan if not, then upserts.
 func (s *Service) ensureAnimeExists(ctx context.Context, animeID int64) error {
 	_, err := s.db.GetAnime(ctx, animeID)
 	if err == nil {
-		return nil
+		return nil // already exists
 	}
 
+	// fetch from jikan and store locally
 	anime, err := s.jikanClient.GetAnimeByID(ctx, int(animeID))
 	if err != nil {
 		return fmt.Errorf("failed to fetch anime from jikan: %w", err)
@@ -72,6 +74,7 @@ type AddRequest struct {
 	Airing        bool
 }
 
+// AddToWatchlist adds or updates an anime entry in user's watchlist.
 func (s *Service) AddToWatchlist(ctx context.Context, userID string, animeID int64, status string) error {
 	if animeID <= 0 {
 		return ErrInvalidAnimeID
@@ -81,6 +84,7 @@ func (s *Service) AddToWatchlist(ctx context.Context, userID string, animeID int
 		return ErrInvalidStatus
 	}
 
+	// ensure anime exists in local db before linking
 	if err := s.ensureAnimeExists(ctx, animeID); err != nil {
 		return err
 	}
@@ -101,6 +105,7 @@ func (s *Service) AddToWatchlist(ctx context.Context, userID string, animeID int
 	return nil
 }
 
+// RemoveEntry deletes a watchlist entry and returns the anime for potential use.
 func (s *Service) RemoveEntry(ctx context.Context, userID string, animeID int64) (db.Anime, error) {
 	if animeID <= 0 {
 		return db.Anime{}, ErrInvalidAnimeID
@@ -122,6 +127,7 @@ func (s *Service) RemoveEntry(ctx context.Context, userID string, animeID int64)
 	return anime, nil
 }
 
+// GetUserWatchlist retrieves all watchlist entries for a user.
 func (s *Service) GetUserWatchlist(ctx context.Context, userID string) ([]db.GetUserWatchListRow, error) {
 	entries, err := s.db.GetUserWatchList(ctx, userID)
 	if err != nil {
@@ -130,6 +136,7 @@ func (s *Service) GetUserWatchlist(ctx context.Context, userID string) ([]db.Get
 	return entries, nil
 }
 
+// GetContinueWatching retrieves entries for continue watching section.
 func (s *Service) GetContinueWatching(ctx context.Context, userID string) ([]db.GetContinueWatchingEntriesRow, error) {
 	if strings.TrimSpace(userID) == "" {
 		return nil, errors.New("invalid user id")
@@ -143,6 +150,8 @@ func (s *Service) GetContinueWatching(ctx context.Context, userID string) ([]db.
 	return entries, nil
 }
 
+// DeleteContinueWatching removes entry and clears associated watch progress.
+// uses transaction when sqlDB is available.
 func (s *Service) DeleteContinueWatching(ctx context.Context, userID string, animeID int64) error {
 	if strings.TrimSpace(userID) == "" {
 		return errors.New("invalid user id")
@@ -164,6 +173,7 @@ func (s *Service) DeleteContinueWatching(ctx context.Context, userID string, ani
 		AnimeID:            animeID,
 	}
 
+	// use transaction when sqlDB available for consistency
 	if s.sqlDB == nil {
 		if err := s.db.DeleteContinueWatchingEntry(ctx, params); err != nil {
 			return fmt.Errorf("failed to delete continue watching entry: %w", err)