chore(api): update swagger method descripitons (#8728)

Speaking from personal experience, when exploring the API I find myself trying to parse the exact meaning of many descriptions for a while, and I also have to get used to many different kinds of inconsistencies and grammar issues.

This PR improves a few of these. Some I tried to reword to make them easier to understand, for others I just improved consistency a little, like capitalization. This area needs more work, this PR just makes some progress. Anything that is improved in this one can be improved further in later PRs, so in review please focus on regressions if you find any.

Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/8728
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Co-authored-by: 0ko <0ko@noreply.codeberg.org>
Co-committed-by: 0ko <0ko@noreply.codeberg.org>

routers/api/v1/user/settings.go

@@ -14,11 +14,11 @@ import (
 	user_service "forgejo.org/services/user"
 )
 
-// GetUserSettings returns user settings
+// GetUserSettings returns doer's account settings
 func GetUserSettings(ctx *context.APIContext) {
 	// swagger:operation GET /user/settings user getUserSettings
 	// ---
-	// summary: Get user settings
+	// summary: Get current user's account settings
 	// produces:
 	// - application/json
 	// responses:
@@ -31,11 +31,11 @@ func GetUserSettings(ctx *context.APIContext) {
 	ctx.JSON(http.StatusOK, convert.User2UserSettings(ctx.Doer))
 }
 
-// UpdateUserSettings returns user settings
+// UpdateUserSettings updates settings in doer's account
 func UpdateUserSettings(ctx *context.APIContext) {
 	// swagger:operation PATCH /user/settings user updateUserSettings
 	// ---
-	// summary: Update user settings
+	// summary: Update settings in current user's account
 	// parameters:
 	// - name: body
 	//   in: body