refactor: trim verbose comments across branch additions

Shrinks multi-paragraph godocs and orienting prose added on this branch
to one-sentence whys. Keeps the non-obvious rationale (TOCTOU, SQLite
read-across-write deadlock, echojwt-401-before-license-gate, xorm:"-"
hydration, LIKE semantics in search, stale-JWT re-read, paid-bypass
gating) and drops narration of what the next line does. No behavioural
change.

Author: kolaente

frontend/src/components/input/FormField.test.ts

@@ -233,8 +233,7 @@ describe('FormField', () => {
 			},
 		})
 		const label = wrapper.find('label.two-col')
-		// for would point to a different id than the slotted control generates,
-		// so omit it entirely and rely on the label wrapping the control.
+		// for="" would mismatch the slotted control's id; rely on the label wrapping instead.
 		expect(label.attributes('for')).toBeUndefined()
 		expect(label.find('input').exists()).toBe(true)
 	})

frontend/src/components/input/FormSelect.test.ts

@@ -155,9 +155,7 @@ describe('FormSelect', () => {
 			},
 		})
 		const select = wrapper.find('select')
-		// Without an explicit value binding, the native select defaults to the
-		// first option. If the component forced :value="undefined" that default
-		// would be broken.
+		// Forcing :value="undefined" would break the native default-to-first-option behavior.
 		expect((select.element as HTMLSelectElement).value).toBe('')
 	})
 

frontend/src/router/index.ts

@@ -503,16 +503,12 @@ router.beforeEach(async (to, from) => {
 	await authStore.checkAuth()
 
 	if (to.meta?.requiresAdminPanel) {
-		// On a hard refresh or direct navigation to /admin, this guard runs
-		// before loadApp() has fetched /info, so enabledProFeatures is still
-		// the default empty array. Await the in-flight startup so the license
-		// check sees the real state instead of silently redirecting.
+		// Await loadApp() so the license check doesn't race the empty default on direct /admin navigation.
 		const baseStore = useBaseStore()
 		await baseStore.appReady
 		const configStore = useConfigStore()
 		const featureOn = configStore.isProFeatureEnabled('admin_panel')
-		// `isAdmin` comes from `/user`, not the JWT — fetch directly in case
-		// the concurrent checkAuth() was debounced and the store is still hydrating.
+		// isAdmin comes from /user, not the JWT; force-fetch in case checkAuth() was debounced.
 		if (authStore.info?.isAdmin === undefined) {
 			await authStore.refreshUserInfo()
 		}

frontend/src/stores/base.ts

@@ -152,11 +152,7 @@ export const useBaseStore = defineStore('base', () => {
 				// and only use a previously stored API URL from localStorage.
 				const storedApiUrl = localStorage.getItem('API_URL')
 				if (storedApiUrl) {
-					// Run the stored URL through checkAndSetApiUrl so /info is
-					// fetched before we mark the app ready. Without this,
-					// configStore.enabledProFeatures stays empty for returning
-					// desktop users and every pro-feature gate (admin panel,
-					// etc.) fails for the whole session.
+					// Hydrate /info before marking ready; otherwise pro-feature gates stay off for returning desktop users.
 					await checkAndSetApiUrl(storedApiUrl)
 					await authStore.checkAuth()
 				}
@@ -182,8 +178,7 @@ export const useBaseStore = defineStore('base', () => {
 		}
 	}
 
-	// Track the in-flight loadApp() so router guards can await config/auth
-	// hydration instead of racing the default empty state on direct navigation.
+	// Exposed so router guards can await config/auth hydration on direct navigation.
 	const appReady = loadApp()
 
 	return {

frontend/src/views/admin/UsersView.vue

@@ -377,9 +377,7 @@ function goToPage(page: number) {
 }
 
 const onSearch = useDebounceFn(() => {
-	// A new search must restart at page 1 — the previous page index is
-	// meaningless against a different result set and would stick the UI on an
-	// empty page when the new search is narrower.
+	// Reset to page 1 so a narrower search doesn't strand the UI on an empty page.
 	currentPage.value = 1
 	load()
 }, 300)

pkg/cmd/user.go

@@ -123,9 +123,7 @@ var userSetAdminCmd = &cobra.Command{
 		initialize.FullInit()
 	},
 	Run: func(_ *cobra.Command, args []string) {
-		// The is_admin flag only unlocks behavior that lives behind the admin
-		// panel entitlement; setting it on a free instance would hand out paid
-		// capabilities without the license check used everywhere else.
+		// Refuse on a free instance; the is_admin bypass is gated by the admin-panel entitlement everywhere else.
 		if !license.IsFeatureEnabled(license.FeatureAdminPanel) {
 			log.Fatalf("The admin-panel license feature is not active; refusing to change the is_admin flag.")
 		}

pkg/routes/api/v1/admin/user_create.go

@@ -29,9 +29,7 @@ import (
 	"github.com/labstack/echo/v5"
 )
 
-// CreateUserBody is the payload accepted by the admin create-user endpoint.
-// It wraps user.APIUserPassword (username/password/email with the usual
-// validation) and adds the admin-only fields that only make sense here.
+// CreateUserBody wraps user.APIUserPassword with admin-only fields.
 type CreateUserBody struct {
 	// The full name of the new user. Optional.
 	Name string `json:"name"`
@@ -91,9 +89,7 @@ func CreateUser(c *echo.Context) error {
 		newUser.IsAdmin = true
 	}
 
-	// CreateUser flips status to EmailConfirmationRequired only when the mailer
-	// is on; otherwise the user is already Active and this is a no-op. Force
-	// Active when the admin asked to skip, or when no mailer is configured.
+	// Force Active when the admin asked to skip, or when no mailer exists to send the confirmation.
 	if body.SkipEmailConfirm || !config.MailerEnabled.GetBool() {
 		if err := user.SetUserStatus(s, newUser, user.StatusActive); err != nil {
 			_ = s.Rollback()

pkg/routes/api/v1/admin/users.go

@@ -24,7 +24,7 @@ import (
 	"xorm.io/xorm"
 )
 
-// User re-exposes fields hidden by the default User JSON view.
+// User re-exposes fields hidden by the default user.User JSON view.
 type User struct {
 	*user.User
 	IsAdmin      bool        `json:"is_admin"`
@@ -64,9 +64,7 @@ func resolveAuthProvider(u *user.User, providers []*openid.Provider) string {
 	return u.Issuer
 }
 
-// UserList is the CRUDable wrapper backing the admin list-users route via
-// handler.ReadAllWeb. Only ReadAll is used; everything else is gated by
-// the RequireInstanceAdmin middleware.
+// UserList backs the admin list-users route via handler.ReadAllWeb; only ReadAll is used.
 type UserList struct{}
 
 // ReadAll returns paginated users, optionally filtered by username/email.

pkg/routes/api/v1/admin/users_admin.go

@@ -28,8 +28,7 @@ import (
 )
 
 type IsAdminPatch struct {
-	// Pointer so a missing field binds as nil rather than the zero value.
-	// Without this an empty body would silently demote the target user.
+	// Pointer to distinguish "omitted" from false; an empty body would silently demote otherwise.
 	IsAdmin *bool `json:"is_admin"`
 }
 

pkg/routes/api/v1/admin/users_mgmt.go

@@ -28,8 +28,7 @@ import (
 )
 
 type StatusPatch struct {
-	// Pointer so a missing field binds as nil rather than StatusActive.
-	// Without this an empty body would silently re-enable the target user.
+	// Pointer to distinguish "omitted" from StatusActive; an empty body would silently re-enable otherwise.
 	Status *user.Status `json:"status"`
 }
 
@@ -75,8 +74,7 @@ func PatchStatus(c *echo.Context) error {
 		return user.ErrUserDoesNotExist{UserID: id}
 	}
 
-	// Any non-Active status blocks login, so moving an admin out of Active is
-	// equivalent to demoting them — email-confirmation included.
+	// Any non-Active status blocks login, so moving an admin out of Active is equivalent to demotion.
 	if target.IsAdmin && newStatus != user.StatusActive {
 		if err := user.GuardLastAdmin(s, target); err != nil {
 			_ = s.Rollback()
@@ -92,7 +90,7 @@ func PatchStatus(c *echo.Context) error {
 		return err
 	}
 
-	// Refresh locally; GetUserByID refuses disabled accounts.
+	// Refresh locally since GetUserByID refuses disabled accounts.
 	target.Status = newStatus
 	providers, err := openid.GetAllProviders()
 	if err != nil {