chore: improve doc string in code

Signed-off-by: Alexandre Couedelo <[email protected]>

document/metadata.go

@@ -45,7 +45,7 @@ func ParseRegoWithAnnotations(directory string) (ast.FlatAnnotationsRefSet, erro
 // Document represent a page of the documentation
 type Document []Section
 
-// Section sequencial piece of documention comprise of ast.Annotations and some pre-processed fields
+// Section is a sequential piece of documentation comprised of ast.Annotations and some pre-processed fields
 // This struct exist because some fields of ast.Annotations are not easy to manipulate in go-template
 type Section struct {
 	// Path is the string representation of ast.Annotations.Path
@@ -59,7 +59,7 @@ type Section struct {
 	Annotations *ast.Annotations
 }
 
-// Equal is only relevant for test ans asset that two ection are partially Equal
+// Equal is only relevant for tests and assert that two sections are partially Equal
 func (s Section) Equal(s2 Section) bool {
 	if s.H == s2.H &&
 		s.Path == s2.Path &&
@@ -70,11 +70,11 @@ func (s Section) Equal(s2 Section) bool {
 	return false
 }
 
-// ConvertAnnotationsToSections generate a more convenient struct that can be used to generate the doc
-// First concern is to build a coherent title structure, the ideal case is that each package and each rule as a doc,
-// but this is not guaranteed. I couldn't find a way to call strings.Repeat inside go-template, thus the title symbol is
+// ConvertAnnotationsToSections generates a more convenient struct that can be used to generate the doc
+// First concern is to build a coherent title structure; the ideal case is that each package and each rule has a doc,
+// but this is not guaranteed. I couldn't find a way to call `strings.Repeat` inside go-template; thus, the title symbol is
 // directly provided as markdown (#, ##, ###, etc.)
-// Second the attribute Path of ast.Annotations are not easy to used on go-template, thus we extract it as a string
+// Second, the attribute Path of ast.Annotations are not easy to use on go-template; thus, we extract it as a string
 func ConvertAnnotationsToSections(as ast.FlatAnnotationsRefSet) (Document, error) {
 
 	var d Document

document/metadata_test.go

@@ -40,7 +40,7 @@ func getTestModules(t *testing.T, modules [][]string) ast.FlatAnnotationsRefSet
 
 // PartialEqual asserts that two objects are equal, depending on what equal means
 // For instance, you may pass options to ignore certain fields
-// Also if a struct export an Equal func this will be used for the assertion
+// Also, if a struct exports an Equal func this will be used for the assertion
 func PartialEqual(t *testing.T, expected, actual any, diffOpts cmp.Option, msgAndArgs ...any) {
 	t.Helper()
 

document/template.go

@@ -35,7 +35,7 @@ func NewTemplateConfig() *TemplateConfig {
 type RenderDocumentOption func(*TemplateConfig)
 
 // WithTemplate is a functional option to override the documentation template
-// when overriding the template we assume it is located on the host file system
+// When overriding the template, we assume it is located on the host file system
 func WithTemplate(tpl string) RenderDocumentOption {
 	return func(c *TemplateConfig) {
 		c.kind = FS