Make comments more useful

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)