Make comments more useful

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{"&", "<", ">", """, "'"}
@@ -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)
 }