fill in more code comments

internal/cache/timeline/status.go

@@ -243,7 +243,8 @@ func (t *StatusTimelines) ClearAll() {
 // StatusTimeline ...
 type StatusTimeline struct {
 
-	// underlying cache of *StatusMeta{}, primary-keyed by ID string.
+	// underlying timeline cache of *StatusMeta{},
+	// primary-keyed by ID, with extra indices below.
 	cache structr.Timeline[*StatusMeta, string]
 
 	// fast-access cache indices.
@@ -263,12 +264,11 @@ type StatusTimeline struct {
 
 	// defines the 'maximum' count of
 	// entries in the timeline that we
-	// apply our Trim() operation
+	// apply our Trim() call threshold
-	// threshold to. the timeline itself
+	// to. the timeline itself does not
-	// does not limit items due to absurd
+	// limit items due to complexities
-	// complexities it would introduce,
+	// it would introduce, so we apply
-	// so we we apply a 'cut-off' via
+	// a 'cut-off' at regular intervals.
-	// regular calls to Trim(threshold).
 	max int
 }
 
@@ -363,6 +363,11 @@ func (t *StatusTimeline) Load(
 		panic("nil load page func")
 	}
 
+	// TODO: there's quite a few opportunities for
+	// optimization here, with a lot of frequently
+	// used slices of the same types. depending on
+	// profiles it may be advantageous to pool some.
+
 	// Get paging details.
 	lo := page.Min.Value
 	hi := page.Max.Value

internal/processing/timeline/faved.go

@@ -31,6 +31,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/util"
 )
 
+// FavedTimelineGet ...
 func (p *Processor) FavedTimelineGet(ctx context.Context, authed *apiutil.Auth, maxID string, minID string, limit int) (*apimodel.PageableResponse, gtserror.WithCode) {
 	statuses, nextMaxID, prevMinID, err := p.state.DB.GetFavedTimeline(ctx, authed.Account.ID, maxID, minID, limit)
 	if err != nil && !errors.Is(err, db.ErrNoEntries) {

internal/processing/timeline/notification.go

@@ -36,6 +36,7 @@ import (
 	"github.com/superseriousbusiness/gotosocial/internal/util"
 )
 
+// NotificationsGet ...
 func (p *Processor) NotificationsGet(
 	ctx context.Context,
 	authed *apiutil.Auth,

internal/processing/timeline/timeline.go

@@ -96,7 +96,7 @@ func (p *Processor) getStatusTimeline(
 		// Get a list of all account mutes for requester.
 		allMutes, err := p.state.DB.GetAccountMutes(ctx,
 			requester.ID,
-			nil, // nil page, i.e. all
+			nil, // i.e. all
 		)
 		if err != nil && !errors.Is(err, db.ErrNoEntries) {
 			err := gtserror.Newf("error getting account mutes: %w", err)
@@ -111,16 +111,19 @@ func (p *Processor) getStatusTimeline(
 	// input paging cursor.
 	id.ValidatePage(page)
 
-	// ...
+	// Load status page via timeline cache, also
+	// getting lo, hi values for next, prev pages.
 	apiStatuses, lo, hi, err := timeline.Load(ctx,
 
-		// ...
+		// Status page
+		// to load.
 		page,
 
-		// ...
+		// Caller provided database
+		// status page loading function.
 		loadPage,
 
-		// ...
+		// Status load function for cached timeline entries.
 		func(ids []string) ([]*gtsmodel.Status, error) {
 			return p.state.DB.GetStatusesByIDs(ctx, ids)
 		},
@@ -133,7 +136,7 @@ func (p *Processor) getStatusTimeline(
 		// i.e. filter after caching.
 		postFilter,
 
-		// ...
+		// Frontend API model preparation function.
 		func(status *gtsmodel.Status) (*apimodel.Status, error) {
 			apiStatus, err := p.converter.StatusToAPIStatus(ctx,
 				status,