Improved code documentation

arn/APIKeys.go

@@ -16,7 +16,7 @@ var Root = os.Getenv("ARN_ROOT")
 // APIKeys are global API keys for several services
 var APIKeys APIKeysData
 
-// APIKeysData ...
+// APIKeysData represents the API keys defined in "security/api-keys.json".
 type APIKeysData struct {
 	Google struct {
 		ID     string `json:"id"`

arn/Anime.go

@@ -260,7 +260,7 @@ func (anime *Anime) Prequels() []*Anime {
 	return prequels
 }
 
-// ImageLink ...
+// ImageLink requires a size parameter and returns a link to the image in the given size.
 func (anime *Anime) ImageLink(size string) string {
 	extension := ".jpg"
 
@@ -296,7 +296,7 @@ func (anime *Anime) Season() string {
 	return DateToSeason(anime.StartDateTime())
 }
 
-// Characters ...
+// Characters returns the anime characters for this anime.
 func (anime *Anime) Characters() *AnimeCharacters {
 	characters, _ := GetAnimeCharacters(anime.ID)
 
@@ -623,7 +623,8 @@ func (anime *Anime) UpcomingEpisode() *UpcomingEpisode {
 	return nil
 }
 
-// EpisodeCountString ...
+// EpisodeCountString formats the episode count and displays
+// a question mark when the number of episodes is unknown.
 func (anime *Anime) EpisodeCountString() string {
 	if anime.EpisodeCount == 0 {
 		return "?"

arn/AnimeCharacter.go

@@ -8,13 +8,13 @@ func init() {
 	}
 }
 
-// AnimeCharacter ...
+// AnimeCharacter contains the information for a character and his role in an anime.
 type AnimeCharacter struct {
 	CharacterID string `json:"characterId" editable:"true"`
 	Role        string `json:"role" editable:"true" datalist:"anime-character-roles"`
 }
 
-// Character ...
+// Character returns the referenced character.
 func (char *AnimeCharacter) Character() *Character {
 	character, _ := GetCharacter(char.CharacterID)
 	return character

arn/AnimeListItem.go

@@ -9,7 +9,7 @@ const (
 	AnimeListStatusDropped   = "dropped"
 )
 
-// AnimeListItem ...
+// AnimeListItem represents a single item in an anime list.
 type AnimeListItem struct {
 	AnimeID      AnimeID             `json:"animeId"`
 	Status       string              `json:"status" editable:"true"`

arn/AnimeRating.go

@@ -1,20 +1,22 @@
 package arn
 
-// DefaultRating is the default rating value.
-const DefaultRating = 0.0
+const (
+	// DefaultRating is the default rating value.
+	DefaultRating = 0.0
 
-// AverageRating is the center rating in the system.
-// Note that the mathematically correct center would be a little higher,
-// but we don't care about these slight offsets.
-const AverageRating = 5.0
+	// AverageRating is the center rating in the system.
+	// Note that the mathematically correct center would be a little higher,
+	// but we don't care about these slight offsets.
+	AverageRating = 5.0
 
-// MaxRating is the maximum rating users can give.
-const MaxRating = 10.0
+	// MaxRating is the maximum rating users can give.
+	MaxRating = 10.0
 
-// RatingCountThreshold is the number of users threshold that, when passed, doesn't dampen the result.
-const RatingCountThreshold = 4
+	// RatingCountThreshold is the number of users threshold that, when passed, doesn't dampen the result.
+	RatingCountThreshold = 4
+)
 
-// AnimeRating ...
+// AnimeRating represents the rating information for an anime.
 type AnimeRating struct {
 	AnimeListItemRating
 

arn/AnimeRelation.go

@@ -16,7 +16,7 @@ func init() {
 	}
 }
 
-// AnimeRelation ...
+// AnimeRelation represents a relation to another anime.
 type AnimeRelation struct {
 	AnimeID AnimeID `json:"animeId" editable:"true"`
 	Type    string  `json:"type" editable:"true" datalist:"anime-relation-types"`

arn/HSLColor.go

@@ -6,7 +6,7 @@ import (
 	"math"
 )
 
-// HSLColor ...
+// HSLColor represents a color in the HSL format.
 type HSLColor struct {
 	Hue        float64 `json:"hue"`
 	Saturation float64 `json:"saturation"`

arn/autocorrect/AutoCorrect.go

@@ -92,7 +92,7 @@ func PostText(text string) string {
 	return text
 }
 
-// ThreadTitle ...
+// ThreadTitle fixes a thread title by trimming spaces.
 func ThreadTitle(title string) string {
 	return strings.TrimSpace(title)
 }

pages/calendar/calendar.go

@@ -21,7 +21,7 @@ var weekdayNames = []string{
 	"Saturday",
 }
 
-// Get ...
+// Get renders the calendar page.
 func Get(ctx aero.Context) error {
 	user := utils.GetUser(ctx)
 	oneWeek := 7 * 24 * time.Hour

pages/explore/explore.go

@@ -10,7 +10,7 @@ import (
 	"github.com/animenotifier/notify.moe/utils"
 )
 
-// Filter ...
+// Filter filters the anime for the explore page.
 func Filter(ctx aero.Context) error {
 	year := ctx.Get("year")
 	season := ctx.Get("season")

utils/editform/editform.go

@@ -102,7 +102,8 @@ func RenderObject(b *strings.Builder, obj interface{}, idPrefix string) {
 	}
 }
 
-// RenderField ...
+// RenderField renders a single field. If that field is a struct,
+// it will recursively go through all subfields.
 func RenderField(b *strings.Builder, v *reflect.Value, field reflect.StructField, idPrefix string) {
 	fieldValue := reflect.Indirect(v.FieldByName(field.Name))