Make comments more useful

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 {