From 9ab48787d4304a4ef245cf650b89321fa4837dd6 Mon Sep 17 00:00:00 2001
From: Jason Streifling <jason@streifling.com>
Date: Fri, 24 Jan 2025 23:06:32 +0100
Subject: [PATCH] Make comments more useful

---
 atom.go               | 27 +++++++++++++++------------
 category.go           |  3 ++-
 commonAttributes.go   |  6 +++---
 content.go            |  5 ++++-
 date.go               |  4 ++--
 entry.go              | 43 +++++++++++++++++++++++--------------------
 extensionElement.go   |  4 ++--
 feed.go               | 37 ++++++++++++++++++++-----------------
 generator.go          |  3 ++-
 icon.go               |  2 +-
 id.go                 |  2 +-
 inlineOtherContent.go |  4 ++--
 inlineTextContent.go  |  4 ++--
 inlineXHTMLContent.go |  4 ++--
 link.go               |  2 +-
 logo.go               |  2 +-
 outOfLineContent.go   |  4 ++--
 person.go             |  7 ++++---
 plainText.go          |  3 ++-
 source.go             | 31 ++++++++++++++++---------------
 text.go               |  5 ++++-
 xhtmlDiv.go           |  3 ++-
 xhtmlText.go          |  3 ++-
 23 files changed, 115 insertions(+), 93 deletions(-)

diff --git a/atom.go b/atom.go
index 79ddffb..3cb913a 100644
--- a/atom.go
+++ b/atom.go
@@ -16,7 +16,8 @@ type Countable interface {
 	*xml.Attr | *Person | *Category | *Link | *ExtensionElement | *Entry
 }
 
-// addToSlice adds a Countable to to a *[]Countable. It returns an int.
+// addToSlice adds a Countable countable to to a *[]Countable slice. It returns
+// the index as an int.
 func addToSlice[C Countable](slice *[]C, countable C) int {
 	if *slice == nil {
 		*slice = make([]C, 0)
@@ -26,8 +27,8 @@ func addToSlice[C Countable](slice *[]C, countable C) int {
 	return len(*slice) - 1
 }
 
-// deleteFromSlice deletes the Countable with the index from the *[]Countable.
-// It return an error.
+// deleteFromSlice deletes the Countable at index from the *[]Countable slice.
+// It returns an error.
 func deleteFromSlice[C Countable](slice *[]C, index int) error {
 	length := len(*slice)
 	if index > length {
@@ -45,7 +46,7 @@ func isValidIRI(iri string) bool {
 	return regexp.MustCompile(pattern).MatchString(iri)
 }
 
-// isCorrectlyEscaped checks whether a string is correctly escaped as per
+// isCorrectlyEscaped checks whether the text is correctly escaped as per
 // RFC4287. It returns a bool.
 func isCorrectlyEscaped(text string) bool {
 	relevantEntities := []string{"&amp;", "&lt;", "&gt;", "&quot;", "&apos;"}
@@ -59,8 +60,8 @@ func isCorrectlyEscaped(text string) bool {
 	return true
 }
 
-// isCompositeMediaType checks whether a string is a composite media type. It
-// returns a bool.
+// isCompositeMediaType checks whether the string m is a composite media type.
+// It returns a bool.
 func isCompositeMediaType(m string) bool {
 	mediaType, _, err := mime.ParseMediaType(m)
 	if err != nil {
@@ -70,7 +71,7 @@ func isCompositeMediaType(m string) bool {
 	return strings.HasPrefix(mediaType, "multipart/") || strings.HasPrefix(mediaType, "message/")
 }
 
-// isXMLMediaType checks whether a string is an xml media type. It returns a
+// isXMLMediaType checks whether the string m is an xml media type. It returns a
 // bool.
 func isXMLMediaType(m string) bool {
 	mediaType, _, err := mime.ParseMediaType(m)
@@ -81,8 +82,8 @@ func isXMLMediaType(m string) bool {
 	return strings.HasSuffix(mediaType, "/xml") || strings.HasSuffix(mediaType, "+xml")
 }
 
-// isValidMediaType checks whether a string is a valid media type. It returns a
-// bool.
+// isValidMediaType checks whether the string m is a valid media type. It
+// returns a bool.
 func isValidMediaType(m string) bool {
 	mediaType, _, err := mime.ParseMediaType(m)
 	if err != nil {
@@ -93,13 +94,15 @@ func isValidMediaType(m string) bool {
 	return len(typeParts) == 2 && typeParts[0] != "" && typeParts[1] != ""
 }
 
-// isValidLanguageTag checks whether a LanguageTag is valid. It returns a bool.
+// isValidLanguageTag checks whether the string languageTag is valid. It returns
+// a bool.
 func isValidLanguageTag(languageTag string) bool {
 	_, err := language.Parse(languageTag)
 	return err == nil
 }
 
-// isValidAttribute checks whether an Attribute is valid. It returns a bool.
+// isValidAttribute checks whether the string attribute is valid. It returns a
+// bool.
 func isValidAttribute(attribute string) bool {
 	return regexp.MustCompile(`^[a-zA-Z0-9_]+="[^"]*"$`).MatchString(attribute)
 }
@@ -109,7 +112,7 @@ func NewURN() string {
 	return fmt.Sprint("urn:uuid:", uuid.New())
 }
 
-// Unescape unescapes a string. It returns an IRI.
+// Unescape unescapes the string s. It returns an IRI.
 func Unescape(s string) string {
 	return html.UnescapeString(s)
 }
diff --git a/category.go b/category.go
index 16ef541..0f452d4 100644
--- a/category.go
+++ b/category.go
@@ -13,7 +13,8 @@ type Category struct {
 	Label  string `xml:"label,attr,omitempty"`  // Must be unescaped
 }
 
-// NewCategory creates a new Category. It returns a *Category.
+// NewCategory creates a new Category. It takes in a string term and returns a
+// *Category.
 func NewCategory(term string) *Category {
 	return &Category{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/commonAttributes.go b/commonAttributes.go
index bbc5574..bf0c66e 100644
--- a/commonAttributes.go
+++ b/commonAttributes.go
@@ -17,14 +17,14 @@ func NewCommonAttributes() *CommonAttributes {
 	return new(CommonAttributes)
 }
 
-// AddAttribute adds the attribute to the CommonAttributes. It returns its index
-// as an int.
+// AddAttribute adds an attribute to the CommonAttributes. It takes in the
+// strings name and value and returns the index as an int.
 func (c *CommonAttributes) AddAttribute(name, value string) int {
 	return addToSlice(&c.UndefinedAttributes, &xml.Attr{Name: xml.Name{Local: name}, Value: value})
 }
 
 // DeleteAttribute deletes the attribute at index from the CommonAttributes. It
-// return an error.
+// returns an error.
 func (c *CommonAttributes) DeleteAttribute(index int) error {
 	if err := deleteFromSlice(&c.UndefinedAttributes, index); err != nil {
 		return fmt.Errorf("error deleting undefined attribute %v from common attributes %v: %v", index, c, err)
diff --git a/content.go b/content.go
index ba316db..3eafde5 100644
--- a/content.go
+++ b/content.go
@@ -14,7 +14,10 @@ type Content interface {
 	Check() error
 }
 
-// NewContent creates a new Content. It returns a Content and an error.
+// NewContent creates a new Content. It takes in an int contentType, a string
+// mediaType and an any content and returns a Content.
+//
+// If contentType is invalid, it returns nil.
 func NewContent(contentType int, mediaType string, content any) Content {
 	switch contentType {
 	case 0:
diff --git a/date.go b/date.go
index 35b14ff..307866e 100644
--- a/date.go
+++ b/date.go
@@ -10,13 +10,13 @@ type Date struct {
 	DateTime string `xml:",chardata"`
 }
 
-// DateTime formats a time.Time to string formated as defined by RFC3339. It
+// DateTime formats the time.Time t to a string as defined by RFC3339. It
 // returns a string.
 func DateTime(t time.Time) string {
 	return t.Format(time.RFC3339)
 }
 
-// NewDate creates a new Date. It returns a *Date.
+// NewDate creates a new Date. It takes in a time.Time t and returns a *Date.
 func NewDate(t time.Time) *Date {
 	return &Date{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/entry.go b/entry.go
index 38f2524..bd77f87 100644
--- a/entry.go
+++ b/entry.go
@@ -30,14 +30,15 @@ type Entry struct {
 }
 
 // checkAuthors checks the entry's authors for incompatibilities with RFC4287.
-// It returns an errors.
+// It takes in a bool authorIsInFeed and returns an errors.
+//
 // atom:entry elements MUST contain one or more atom:author elements, unless
 // the atom:entry contains an atom:source element that contains an atom:author
 // element or, in an Atom Feed Document, the atom:feed element contains an
 // atom:author element itself.
-func (e *Entry) checkAuthors(authorInFeed bool) error {
+func (e *Entry) checkAuthors(authorIsInFeed bool) error {
 	if e.Authors == nil {
-		if !authorInFeed {
+		if !authorIsInFeed {
 			if e.Source == nil {
 				return fmt.Errorf("no authors set in entry %v", e.ID.URI)
 			}
@@ -56,7 +57,6 @@ func (e *Entry) checkAuthors(authorInFeed bool) error {
 	return nil
 }
 
-// NewEntry creates a new Entry. It returns a *Entry.
 // update sets the Updated time to time.Now.
 func (e *Entry) update() {
 	if e.Updated == nil {
@@ -66,6 +66,8 @@ func (e *Entry) update() {
 	}
 }
 
+// NewEntry creates a new Entry. It takes in a string title and returns a
+// *Entry.
 func NewEntry(title string) *Entry {
 	return &Entry{
 		CommonAttributes: NewCommonAttributes(),
@@ -75,14 +77,14 @@ func NewEntry(title string) *Entry {
 	}
 }
 
-// AddAuthor adds the Person as an author to the Entry. It returns its index as
-// an int.
-func (e *Entry) AddAuthor(p *Person) int {
-	return addToSlice(&e.Authors, p)
+// AddAuthor adds the Person a as an author to the Entry. It returns the index
+// as an int.
+func (e *Entry) AddAuthor(a *Person) int {
 	e.update()
+	return addToSlice(&e.Authors, a)
 }
 
-// DeleteAuthor deletes the Person at index from the Entry. It return an error.
+// DeleteAuthor deletes the Person at index from the Entry. It returns an error.
 func (e *Entry) DeleteAuthor(index int) error {
 	if err := deleteFromSlice(&e.Authors, index); err != nil {
 		return fmt.Errorf("error deleting author %v from entry %v: %v", index, e.ID.URI, err)
@@ -92,13 +94,13 @@ func (e *Entry) DeleteAuthor(index int) error {
 	return nil
 }
 
-// AddCategory adds the Category to the Entry. It returns ts index as an int.
+// AddCategory adds the Category c to the Entry. It returns the index as an int.
 func (e *Entry) AddCategory(c *Category) int {
 	e.update()
 	return addToSlice(&e.Categories, c)
 }
 
-// DeleteCategory deletes the Category at index from the Entry. It return an
+// DeleteCategory deletes the Category at index from the Entry. It returns an
 // error.
 func (e *Entry) DeleteCategory(index int) error {
 	if err := deleteFromSlice(&e.Categories, index); err != nil {
@@ -109,14 +111,14 @@ func (e *Entry) DeleteCategory(index int) error {
 	return nil
 }
 
-// AddContributor adds the Person as a contributor to the Entry. It returns its
-// index as an int.
+// AddContributor adds the Person c as a contributor to the Entry. It returns
+// the index as an int.
 func (e *Entry) AddContributor(c *Person) int {
 	e.update()
 	return addToSlice(&e.Contributors, c)
 }
 
-// DeleteContributor deletes the Person at index from the Entry. It return an
+// DeleteContributor deletes the Person at index from the Entry. It returns an
 // error.
 func (e *Entry) DeleteContributor(index int) error {
 	if err := deleteFromSlice(&e.Contributors, index); err != nil {
@@ -127,13 +129,13 @@ func (e *Entry) DeleteContributor(index int) error {
 	return nil
 }
 
-// AddLink adds the Link to the Entry. It returns its index as an int.
+// AddLink adds the Link l to the Entry. It returns the index as an int.
 func (e *Entry) AddLink(l *Link) int {
 	e.update()
 	return addToSlice(&e.Links, l)
 }
 
-// DeleteLink deletes the Link at index from the Entry. It return an error.
+// DeleteLink deletes the Link at index from the Entry. It returns an error.
 func (e *Entry) DeleteLink(index int) error {
 	if err := deleteFromSlice(&e.Links, index); err != nil {
 		return fmt.Errorf("error deleting link %v from entry %v: %v", index, e.ID.URI, err)
@@ -143,14 +145,14 @@ func (e *Entry) DeleteLink(index int) error {
 	return nil
 }
 
-// AddExtension adds the ExtensionElement to the Entry. It returns its index as
-// an int.
+// AddExtension adds the ExtensionElement x to the Entry. It returns the index
+// as an int.
 func (e *Entry) AddExtension(x *ExtensionElement) int {
 	e.update()
 	return addToSlice(&e.Extensions, x)
 }
 
-// DeleteExtension deletes the Extension at index from the Entry. It return an
+// DeleteExtension deletes the Extension at index from the Entry. It returns an
 // error.
 func (e *Entry) DeleteExtension(index int) error {
 	if err := deleteFromSlice(&e.Extensions, index); err != nil {
@@ -275,7 +277,8 @@ func (e *Entry) Check() error {
 	return nil
 }
 
-// ToXML converts the Feed to XML. It returns a string and an error.
+// ToXML converts the Feed to XML. It takes in a string encoding and returns a
+// string and an error.
 func (e *Entry) ToXML(encoding string) (string, error) {
 	xml, err := xml.MarshalIndent(e, "", "  ")
 	if err != nil {
diff --git a/extensionElement.go b/extensionElement.go
index c42cd14..54a30bd 100644
--- a/extensionElement.go
+++ b/extensionElement.go
@@ -10,8 +10,8 @@ type ExtensionElement struct {
 	XMLName xml.Name
 }
 
-// NewExtensionElement creates a new ExtensionElement. It returns a
-// *ExtensionElement.
+// NewExtensionElement creates a new ExtensionElement. It takes in a string name
+// and any value and returns a *ExtensionElement.
 func NewExtensionElement(name string, value any) *ExtensionElement {
 	return &ExtensionElement{XMLName: xml.Name{Local: name}, Value: value}
 }
diff --git a/feed.go b/feed.go
index c94a8c8..7c0cb03 100644
--- a/feed.go
+++ b/feed.go
@@ -25,7 +25,6 @@ type Feed struct {
 	Entries      []*Entry            `xml:",omitempty"`
 }
 
-// NewFeed creates a new Feed. It returns a *Feed.
 // update sets the Updated time to time.Now.
 func (f *Feed) update() {
 	if f.Updated == nil {
@@ -35,6 +34,7 @@ func (f *Feed) update() {
 	}
 }
 
+// NewFeed creates a new Feed. It takes in a string title and returns a *Feed.
 func NewFeed(title string) *Feed {
 	return &Feed{
 		CommonAttributes: NewCommonAttributes(),
@@ -44,14 +44,14 @@ func NewFeed(title string) *Feed {
 	}
 }
 
-// AddAuthor adds the Person as an author to the Feed. It returns its index as
+// AddAuthor adds the Person a as an author to the Feed. It returns the index as
 // an int.
-func (f *Feed) AddAuthor(p *Person) int {
-	return addToSlice(&f.Authors, p)
+func (f *Feed) AddAuthor(a *Person) int {
 	f.update()
+	return addToSlice(&f.Authors, a)
 }
 
-// DeleteAuthor deletes the Person at index from the Feed. It return an error.
+// DeleteAuthor deletes the Person at index from the Feed. It returns an error.
 func (f *Feed) DeleteAuthor(index int) error {
 	if err := deleteFromSlice(&f.Authors, index); err != nil {
 		return fmt.Errorf("error deleting author %v from entry %v: %v", index, f.ID.URI, err)
@@ -61,13 +61,13 @@ func (f *Feed) DeleteAuthor(index int) error {
 	return nil
 }
 
-// AddCategory adds the Category to the Feed. It returns its index as an int.
+// AddCategory adds the Category c to the Feed. It returns the index as an int.
 func (f *Feed) AddCategory(c *Category) int {
 	f.update()
 	return addToSlice(&f.Categories, c)
 }
 
-// DeleteCategory deletes the Category at index from the Feed. It return an
+// DeleteCategory deletes the Category at index from the Feed. It returns an
 // error.
 func (f *Feed) DeleteCategory(index int) error {
 	if err := deleteFromSlice(&f.Categories, index); err != nil {
@@ -78,14 +78,14 @@ func (f *Feed) DeleteCategory(index int) error {
 	return nil
 }
 
-// AddContributor adds the Person as a contributor to the Feed. It returns its
+// AddContributor adds the Person c as a contributor to the Feed. It returns the
 // index as an int.
 func (f *Feed) AddContributor(c *Person) int {
 	f.update()
 	return addToSlice(&f.Contributors, c)
 }
 
-// DeleteContributor deletes the Person at index from the Feed. It return an
+// DeleteContributor deletes the Person at index from the Feed. It returns an
 // error.
 func (f *Feed) DeleteContributor(index int) error {
 	if err := deleteFromSlice(&f.Contributors, index); err != nil {
@@ -96,14 +96,15 @@ func (f *Feed) DeleteContributor(index int) error {
 	return nil
 }
 
-// AddLink adds the Link to the Feed. There should be one Link with Rel "self".
-// It returns its index as an int.
+// AddLink adds the Link l to the Feed. It returns the index as an int.
+//
+// There should be one Link with Rel "self".
 func (f *Feed) AddLink(l *Link) int {
 	f.update()
 	return addToSlice(&f.Links, l)
 }
 
-// DeleteLink deletes the Link at index from the Feed. It return an error.
+// DeleteLink deletes the Link at index from the Feed. It returns an error.
 func (f *Feed) DeleteLink(index int) error {
 	if err := deleteFromSlice(&f.Links, index); err != nil {
 		return fmt.Errorf("error deleting link %v from entry %v: %v", index, f.ID.URI, err)
@@ -113,13 +114,14 @@ func (f *Feed) DeleteLink(index int) error {
 	return nil
 }
 
-// AddExtension adds the Extension to the Feed. It returns its index as an int.
+// AddExtension adds the Extension e to the Feed. It returns the index as an
+// int.
 func (f *Feed) AddExtension(e *ExtensionElement) int {
 	f.update()
 	return addToSlice(&f.Extensions, e)
 }
 
-// DeleteExtension deletes the Extension at index from the Feed. It return an
+// DeleteExtension deletes the Extension at index from the Feed. It returns an
 // error.
 func (f *Feed) DeleteExtension(index int) error {
 	if err := deleteFromSlice(&f.Extensions, index); err != nil {
@@ -130,13 +132,13 @@ func (f *Feed) DeleteExtension(index int) error {
 	return nil
 }
 
-// AddEntry adds the Entry to the Feed. It returns its index as an int.
+// AddEntry adds the Entry e to the Feed. It returns the index as an int.
 func (f *Feed) AddEntry(e *Entry) int {
 	f.update()
 	return addToSlice(&f.Entries, e)
 }
 
-// DeleteEntry deletes the Entry at index from the Feed. It return an error.
+// DeleteEntry deletes the Entry at index from the Feed. It returns an error.
 func (f *Feed) DeleteEntry(index int) error {
 	if err := deleteFromSlice(&f.Entries, index); err != nil {
 		return fmt.Errorf("error deleting entry %v from entry %v: %v", index, f.ID.URI, err)
@@ -146,7 +148,8 @@ func (f *Feed) DeleteEntry(index int) error {
 	return nil
 }
 
-// DeleteEntryByURI deletes the Entry from the Feed. It return an error.
+// DeleteEntryByURI deletes the Entry from the Feed. It takes in a string uri
+// and returns an error.
 func (f *Feed) DeleteEntryByURI(uri string) error {
 	if !isValidIRI(uri) {
 		return fmt.Errorf("error deleting entry from feed %v: uri %v invalid", f.ID.URI, uri)
diff --git a/generator.go b/generator.go
index 5087958..a810f9b 100644
--- a/generator.go
+++ b/generator.go
@@ -14,7 +14,8 @@ type Generator struct {
 	Text    string `xml:",chardata"`
 }
 
-// NewGenerator creates a new Generator. It returns a *Generator.
+// NewGenerator creates a new Generator. It takes in a string text and returns a
+// *Generator.
 func NewGenerator(text string) *Generator {
 	return &Generator{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/icon.go b/icon.go
index ebf7d89..b4903ca 100644
--- a/icon.go
+++ b/icon.go
@@ -12,7 +12,7 @@ type Icon struct {
 	URI string `xml:",chardata"` // IRI
 }
 
-// NewIcon creates a new Icon. It returns a *Icon.
+// NewIcon creates a new Icon. It takes in a string uri and returns a *Icon.
 func NewIcon(uri string) *Icon {
 	return &Icon{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/id.go b/id.go
index 3c9b3e3..9929538 100644
--- a/id.go
+++ b/id.go
@@ -12,7 +12,7 @@ type ID struct {
 	URI string `xml:",chardata"` // IRI
 }
 
-// NewID creates a new ID. It returns a *ID.
+// NewID creates a new ID. It takes in a string uri and returns a *ID.
 func NewID(uri string) *ID {
 	return &ID{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/inlineOtherContent.go b/inlineOtherContent.go
index 622efa8..a3e3e87 100644
--- a/inlineOtherContent.go
+++ b/inlineOtherContent.go
@@ -13,8 +13,8 @@ type InlineOtherContent struct {
 	Type       string `xml:"type,attr,omitempty"` // MediaType
 }
 
-// newInlineOtherContent creates a new InlineOtherContent. It returns a
-// *InlineOtherContent and an error.
+// newInlineOtherContent creates a new InlineOtherContent. It takes in the string
+// mediaType and any content and returns a *InlineOtherContent and an error.
 func newInlineOtherContent(mediaType string, content any) *InlineOtherContent {
 	mediaType, _, _ = mime.ParseMediaType(mediaType)
 
diff --git a/inlineTextContent.go b/inlineTextContent.go
index b094cf9..91d3dd9 100644
--- a/inlineTextContent.go
+++ b/inlineTextContent.go
@@ -12,8 +12,8 @@ type InlineTextContent struct {
 	Text string `xml:",chardata"`
 }
 
-// newInlineTextContent creates a new InlineTextContent. It returns a
-// *InlineTextContent.
+// newInlineTextContent creates a new InlineTextContent. It takes in the strings
+// mediaType and text and returns a *InlineTextContent.
 func newInlineTextContent(mediaType, text string) *InlineTextContent {
 	return &InlineTextContent{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/inlineXHTMLContent.go b/inlineXHTMLContent.go
index c115627..4f74b9b 100644
--- a/inlineXHTMLContent.go
+++ b/inlineXHTMLContent.go
@@ -12,8 +12,8 @@ type InlineXHTMLContent struct {
 	Type     string `xml:"type,attr"`
 }
 
-// newInlineXHTMLContent creates a new InlineXHTMLContent. It returns a
-// *InlineXHTMLContent.
+// newInlineXHTMLContent creates a new InlineXHTMLContent. It takes in the
+// string mediaType and the XHTMLDiv div and returns a *InlineXHTMLContent.
 func newInlineXHTMLContent(mediaType string, div *XHTMLDiv) *InlineXHTMLContent {
 	return &InlineXHTMLContent{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/link.go b/link.go
index d90d067..b01182d 100644
--- a/link.go
+++ b/link.go
@@ -17,7 +17,7 @@ type Link struct {
 	Length   uint   `xml:"length,attr,omitempty"`
 }
 
-// NewLink creates a new Link. It returns a *Link.
+// NewLink creates a new Link. It takes in the string href and returns a *Link.
 func NewLink(href string) *Link {
 	return &Link{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/logo.go b/logo.go
index d63ec05..abfd5a1 100644
--- a/logo.go
+++ b/logo.go
@@ -11,7 +11,7 @@ type Logo struct {
 	URI string `xml:",chardata"` // IRI
 }
 
-// NewLogo creates a new Logo. It returns a *Logo.
+// NewLogo creates a new Logo. It takes in a string uri and returns a *Logo.
 func NewLogo(uri string) *Logo {
 	return &Logo{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/outOfLineContent.go b/outOfLineContent.go
index 249819b..a6623b6 100644
--- a/outOfLineContent.go
+++ b/outOfLineContent.go
@@ -13,8 +13,8 @@ type OutOfLineContent struct {
 	SRC  string `xml:"src,attr"`            // IRI
 }
 
-// newOutOfLineContent creates a new OutOfLineContent. It returns a
-// *OutOfLineContent.
+// newOutOfLineContent creates a new OutOfLineContent. It takes in the strings
+// mediaType and src and returns a *OutOfLineContent.
 func newOutOfLineContent(mediaType, src string) *OutOfLineContent {
 	mediaType, _, _ = mime.ParseMediaType(mediaType)
 
diff --git a/person.go b/person.go
index 72c15b8..a90a128 100644
--- a/person.go
+++ b/person.go
@@ -13,7 +13,8 @@ type Person struct {
 	Extensions []*ExtensionElement `xml:",any,omitempty"`
 }
 
-// NewPerson creates a new Person. It returns a *Person.
+// NewPerson creates a new Person. It takes in a string name and returns a
+// *Person.
 func NewPerson(name string) *Person {
 	return &Person{
 		CommonAttributes: NewCommonAttributes(),
@@ -21,13 +22,13 @@ func NewPerson(name string) *Person {
 	}
 }
 
-// AddExtension adds the Extension to the Person. It returns its index as an
+// AddExtension adds the Extension e to the Person. It returns the index as an
 // int.
 func (p *Person) AddExtension(e *ExtensionElement) int {
 	return addToSlice(&p.Extensions, e)
 }
 
-// DeleteExtension deletes the Extension at index from the Person. It return an
+// DeleteExtension deletes the Extension at index from the Person. It returns an
 // error.
 func (p *Person) DeleteExtension(index int) error {
 	if err := deleteFromSlice(&p.Extensions, index); err != nil {
diff --git a/plainText.go b/plainText.go
index a6ef330..7f491ff 100644
--- a/plainText.go
+++ b/plainText.go
@@ -13,7 +13,8 @@ type PlainText struct {
 // isText checks whether the PlainText is a Text. It returns a bool.
 func (p *PlainText) isText() bool { return true }
 
-// newPlainText creates a new PlainText. It returns a *PlainText.
+// newPlainText creates a new PlainText. It takes in the strings textType and
+// content and returns a *PlainText.
 func newPlainText(textType, content string) *PlainText {
 	return &PlainText{
 		CommonAttributes: NewCommonAttributes(),
diff --git a/source.go b/source.go
index ed1093f..43908ce 100644
--- a/source.go
+++ b/source.go
@@ -28,13 +28,14 @@ func NewSource() *Source {
 	return &Source{CommonAttributes: NewCommonAttributes()}
 }
 
-// AddAuthor adds the Person as an author to the Source. It returns its index as
-// an int.
-func (s *Source) AddAuthor(p *Person) int {
-	return addToSlice(&s.Authors, p)
+// AddAuthor adds the Person a as an author to the Source. It returns the index
+// as an int.
+func (s *Source) AddAuthor(a *Person) int {
+	return addToSlice(&s.Authors, a)
 }
 
-// DeleteAuthor deletes the Person at index from the Source. It return an error.
+// DeleteAuthor deletes the Person at index from the Source. It returns an
+// error.
 func (s *Source) DeleteAuthor(index int) error {
 	if err := deleteFromSlice(&s.Authors, index); err != nil {
 		return fmt.Errorf("error deleting author %v from source %v: %v", index, s, err)
@@ -42,12 +43,12 @@ func (s *Source) DeleteAuthor(index int) error {
 	return nil
 }
 
-// AddCategory adds the Category to the Source. It returns its index as an int.
+// AddCategory adds the Category c to the Source. It returns the index as an int.
 func (s *Source) AddCategory(c *Category) int {
 	return addToSlice(&s.Categories, c)
 }
 
-// DeleteCategory deletes the Category at index from the Source. It return an
+// DeleteCategory deletes the Category at index from the Source. It returns an
 // error.
 func (s *Source) DeleteCategory(index int) error {
 	if err := deleteFromSlice(&s.Categories, index); err != nil {
@@ -56,13 +57,13 @@ func (s *Source) DeleteCategory(index int) error {
 	return nil
 }
 
-// AddContributor adds the Person as a contributor to the Source. It returns its
-// index as an int.
+// AddContributor adds the Person c as a contributor to the Source. It returns
+// the index as an int.
 func (s *Source) AddContributor(c *Person) int {
 	return addToSlice(&s.Contributors, c)
 }
 
-// DeleteContributor deletes the Person at index from the Source. It return an
+// DeleteContributor deletes the Person at index from the Source. It returns an
 // error.
 func (s *Source) DeleteContributor(index int) error {
 	if err := deleteFromSlice(&s.Contributors, index); err != nil {
@@ -71,12 +72,12 @@ func (s *Source) DeleteContributor(index int) error {
 	return nil
 }
 
-// AddLink adds the Link to the Source. It returns its index as an int.
+// AddLink adds the Link l to the Source. It returns the index as an int.
 func (s *Source) AddLink(l *Link) int {
 	return addToSlice(&s.Links, l)
 }
 
-// DeleteLink deletes the Link at index from the Source. It return an error.
+// DeleteLink deletes the Link at index from the Source. It returns an error.
 func (s *Source) DeleteLink(index int) error {
 	if err := deleteFromSlice(&s.Links, index); err != nil {
 		return fmt.Errorf("error deleting link %v from source %v: %v", index, s, err)
@@ -84,13 +85,13 @@ func (s *Source) DeleteLink(index int) error {
 	return nil
 }
 
-// AddExtension adds the ExtensionElement to the Source. It returns its index as
-// an int.
+// AddExtension adds the ExtensionElement e to the Source. It returns the index
+// as an int.
 func (s *Source) AddExtension(e *ExtensionElement) int {
 	return addToSlice(&s.Extensions, e)
 }
 
-// DeleteExtension deletes the Extension at index from the Source. It return an
+// DeleteExtension deletes the Extension at index from the Source. It returns an
 // error.
 func (s *Source) DeleteExtension(index int) error {
 	if err := deleteFromSlice(&s.Extensions, index); err != nil {
diff --git a/text.go b/text.go
index c8b0f78..0f27070 100644
--- a/text.go
+++ b/text.go
@@ -7,7 +7,10 @@ type Text interface {
 	Check() error
 }
 
-// NewText creates a new Text. It returns a Text.
+// NewText creates a new Text. It takes in the strings textType and content and
+// returns a Text.
+//
+// If textType is invalid it returns nil.
 func NewText(textType, content string) Text {
 	switch textType {
 	case "text", "":
diff --git a/xhtmlDiv.go b/xhtmlDiv.go
index 0629a37..7cb3801 100644
--- a/xhtmlDiv.go
+++ b/xhtmlDiv.go
@@ -11,7 +11,8 @@ type XHTMLDiv struct {
 	Content string   `xml:",innerxml"`
 }
 
-// NewXHTMLDiv creates a new XHTMLDiv. It returns a *XHTMLDiv.
+// NewXHTMLDiv creates a new XHTMLDiv. It takes in a string content and returns
+// a *XHTMLDiv.
 func NewXHTMLDiv(content string) *XHTMLDiv {
 	return &XHTMLDiv{
 		XMLNS:   "http://www.w3.org/1999/xhtml",
diff --git a/xhtmlText.go b/xhtmlText.go
index e92dc88..677d60d 100644
--- a/xhtmlText.go
+++ b/xhtmlText.go
@@ -13,7 +13,8 @@ type XHTMLText struct {
 // isText checks whether the XHTMLText is a Text. It returns a bool.
 func (x *XHTMLText) isText() bool { return true }
 
-// newPlainText creates a new PlainText. It returns a *PlainText.
+// newPlainText creates a new PlainText. It takes in the strings textType and
+// content and returns a *PlainText.
 func newXHTMLText(textType, content string) *XHTMLText {
 	return &XHTMLText{
 		CommonAttributes: NewCommonAttributes(),