hugolib: Taxonomy GoDoc cleanup

hugolib/site.go

@@ -1293,11 +1293,11 @@ func (s *Site) assembleTaxonomies() {
 				if v, ok := vals.([]string); ok {
 					for _, idx := range v {
 						x := WeightedPage{weight.(int), p}
-						s.Taxonomies[plural].Add(idx, x, s.Info.preserveTaxonomyNames)
+						s.Taxonomies[plural].add(idx, x, s.Info.preserveTaxonomyNames)
 					}
 				} else if v, ok := vals.(string); ok {
 					x := WeightedPage{weight.(int), p}
-					s.Taxonomies[plural].Add(v, x, s.Info.preserveTaxonomyNames)
+					s.Taxonomies[plural].add(v, x, s.Info.preserveTaxonomyNames)
 				} else {
 					jww.ERROR.Printf("Invalid %s in %s\n", plural, p.File.Path())
 				}
@@ -1325,7 +1325,7 @@ func (s *Site) resetPageBuildState() {
 
 func (s *Site) assembleSections() {
 	for i, p := range s.Pages {
-		s.Sections.Add(p.Section(), WeightedPage{s.Pages[i].Weight, s.Pages[i]}, s.Info.preserveTaxonomyNames)
+		s.Sections.add(p.Section(), WeightedPage{s.Pages[i].Weight, s.Pages[i]}, s.Info.preserveTaxonomyNames)
 	}
 
 	for k := range s.Sections {

hugolib/taxonomy.go

@@ -19,40 +19,32 @@ import (
 	"github.com/spf13/hugo/helpers"
 )
 
-/*
+// The TaxonomyList is a list of all taxonomies and their values
- *  An taxonomy list is a list of all taxonomies and their values
+// e.g. List['tags'] => TagTaxonomy (from above)
- *  EG. List['tags'] => TagTaxonomy (from above)
- */
 type TaxonomyList map[string]Taxonomy
 
-/*
+// A Taxonomy is a map of keywords to a list of pages.
- *  An taxonomy is a map of keywords to a list of pages.
+// For example
- *  For example
+//    TagTaxonomy['technology'] = WeightedPages
- *    TagTaxonomy['technology'] = WeightedPages
+//    TagTaxonomy['go']  =  WeightedPages2
- *    TagTaxonomy['go']  =  WeightedPages2
- */
 type Taxonomy map[string]WeightedPages
 
-/*
+// WeightedPages is a list of Pages with their corresponding (and relative) weight
- *  A list of Pages with their corresponding (and relative) weight
+// [{Weight: 30, Page: *1}, {Weight: 40, Page: *2}]
- *  [{Weight: 30, Page: *1}, {Weight: 40, Page: *2}]
- */
 type WeightedPages []WeightedPage
+
+// A WeightedPage is a Page with a weight.
 type WeightedPage struct {
 	Weight int
 	Page   *Page
 }
 
-/*
+// OrderedTaxonomy is another representation of an Taxonomy using an array rather than a map.
- * This is another representation of an Taxonomy using an array rather than a map.
+// Important because you can't order a map.
- * Important because you can't order a map.
- */
 type OrderedTaxonomy []OrderedTaxonomyEntry
 
-/*
+// OrderedTaxonomyEntry is similar to an element of a Taxonomy, but with the key embedded (as name)
- * Similar to an element of an Taxonomy, but with the key embedded (as name)
+// e.g:  {Name: Technology, WeightedPages: Taxonomyedpages}
- * Eg:  {Name: Technology, WeightedPages: Taxonomyedpages}
- */
 type OrderedTaxonomyEntry struct {
 	Name          string
 	WeightedPages WeightedPages
@@ -63,6 +55,7 @@ func kp(in string) string {
 	return helpers.MakePathSanitized(in)
 }
 
+// Get the weighted pages for the given key.
 func (i Taxonomy) Get(key string) WeightedPages {
 	if val, ok := i[key]; ok {
 		return val
@@ -70,15 +63,17 @@ func (i Taxonomy) Get(key string) WeightedPages {
 	return i[kp(key)]
 }
 
+// Count the weighted pages for the given key.
 func (i Taxonomy) Count(key string) int { return len(i[kp(key)]) }
-func (i Taxonomy) Add(key string, w WeightedPage, pretty bool) {
+
+func (i Taxonomy) add(key string, w WeightedPage, pretty bool) {
 	if !pretty {
 		key = kp(key)
 	}
 	i[key] = append(i[key], w)
 }
 
-// Returns an ordered taxonomy with a non defined order
+// TaxonomyArray returns an ordered taxonomy with a non defined order.
 func (i Taxonomy) TaxonomyArray() OrderedTaxonomy {
 	ies := make([]OrderedTaxonomyEntry, len(i))
 	count := 0
@@ -89,41 +84,44 @@ func (i Taxonomy) TaxonomyArray() OrderedTaxonomy {
 	return ies
 }
 
-// Returns an ordered taxonomy sorted by key name
+// Alphabetical returns an ordered taxonomy sorted by key name.
 func (i Taxonomy) Alphabetical() OrderedTaxonomy {
 	name := func(i1, i2 *OrderedTaxonomyEntry) bool {
 		return i1.Name < i2.Name
 	}
 
 	ia := i.TaxonomyArray()
-	OIby(name).Sort(ia)
+	oiBy(name).Sort(ia)
 	return ia
 }
 
-// Returns an ordered taxonomy sorted by # of pages per key
+// ByCount returns an ordered taxonomy sorted by # of pages per key.
 func (i Taxonomy) ByCount() OrderedTaxonomy {
 	count := func(i1, i2 *OrderedTaxonomyEntry) bool {
 		return len(i1.WeightedPages) > len(i2.WeightedPages)
 	}
 
 	ia := i.TaxonomyArray()
-	OIby(count).Sort(ia)
+	oiBy(count).Sort(ia)
 	return ia
 }
 
-// Helper to move the page access up a level
+// Pages returns the Pages for this taxonomy.
 func (ie OrderedTaxonomyEntry) Pages() Pages {
 	return ie.WeightedPages.Pages()
 }
 
+// Count returns the count the pages in this taxonomy.
 func (ie OrderedTaxonomyEntry) Count() int {
 	return len(ie.WeightedPages)
 }
 
+// Term returns the name given to this taxonomy.
 func (ie OrderedTaxonomyEntry) Term() string {
 	return ie.Name
 }
 
+// Reverse reverses the order of the entries in this taxonomy.
 func (t OrderedTaxonomy) Reverse() OrderedTaxonomy {
 	for i, j := 0, len(t)-1; i < j; i, j = i+1, j-1 {
 		t[i], t[j] = t[j], t[i]
@@ -132,20 +130,16 @@ func (t OrderedTaxonomy) Reverse() OrderedTaxonomy {
 	return t
 }
 
-/*
- * Implementation of a custom sorter for OrderedTaxonomies
- */
-
 // A type to implement the sort interface for TaxonomyEntries.
 type orderedTaxonomySorter struct {
 	taxonomy OrderedTaxonomy
-	by       OIby
+	by       oiBy
 }
 
 // Closure used in the Sort.Less method.
-type OIby func(i1, i2 *OrderedTaxonomyEntry) bool
+type oiBy func(i1, i2 *OrderedTaxonomyEntry) bool
 
-func (by OIby) Sort(taxonomy OrderedTaxonomy) {
+func (by oiBy) Sort(taxonomy OrderedTaxonomy) {
 	ps := &orderedTaxonomySorter{
 		taxonomy: taxonomy,
 		by:       by, // The Sort method's receiver is the function (closure) that defines the sort order.
@@ -168,6 +162,7 @@ func (s *orderedTaxonomySorter) Less(i, j int) bool {
 	return s.by(&s.taxonomy[i], &s.taxonomy[j])
 }
 
+// Pages returns the Pages in this weighted page set.
 func (wp WeightedPages) Pages() Pages {
 	pages := make(Pages, len(wp))
 	for i := range wp {
@@ -176,6 +171,8 @@ func (wp WeightedPages) Pages() Pages {
 	return pages
 }
 
+// Prev returns the previous Page relative to the given Page in
+// this weighted page set.
 func (wp WeightedPages) Prev(cur *Page) *Page {
 	for x, c := range wp {
 		if c.Page.UniqueID() == cur.UniqueID() {
@@ -188,6 +185,8 @@ func (wp WeightedPages) Prev(cur *Page) *Page {
 	return nil
 }
 
+// Next returns the next Page relative to the given Page in
+// this weighted page set.
 func (wp WeightedPages) Next(cur *Page) *Page {
 	for x, c := range wp {
 		if c.Page.UniqueID() == cur.UniqueID() {
@@ -202,8 +201,13 @@ func (wp WeightedPages) Next(cur *Page) *Page {
 
 func (wp WeightedPages) Len() int      { return len(wp) }
 func (wp WeightedPages) Swap(i, j int) { wp[i], wp[j] = wp[j], wp[i] }
-func (wp WeightedPages) Sort()         { sort.Stable(wp) }
+
-func (wp WeightedPages) Count() int    { return len(wp) }
+// Sort stable sorts this weighted page set.
+func (wp WeightedPages) Sort() { sort.Stable(wp) }
+
+// Count returns the number of pages in this weighted page set.
+func (wp WeightedPages) Count() int { return len(wp) }
+
 func (wp WeightedPages) Less(i, j int) bool {
 	if wp[i].Weight == wp[j].Weight {
 		if wp[i].Page.Date.Equal(wp[j].Page.Date) {