chore: Fixed changes requested by @boranx

document/document.go

@@ -5,9 +5,9 @@ import (
 	"io"
 )
 
-// GenerateDocument generated a documentation file for a given module by parting
-// A single page is generated for the module located in the indicated directory this includes the package subpackages
-// and rules of the provided path, if you want to split the documentation.
+// GenerateDocument generate a documentation file for a given module
+// A single page is generated for the module located in the indicated directory this includes all package, subpackages
+// and rules of the provided path.
 func GenerateDocument(dir string, tpl string, out io.Writer) error {
 
 	as, err := ParseRegoWithAnnotations(dir)

document/metadata.go

@@ -42,12 +42,24 @@ func ParseRegoWithAnnotations(directory string) (ast.FlatAnnotationsRefSet, erro
 	return as, nil
 }
 
+// Document represent a page of the documentation
+type Document []Section
+
+// Section sequencial piece of documention comprise 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 {
-	H           string
-	Path        string
+	// Path is the string representation of ast.Annotations.Path
+	Path string
+	// Depth represent title depth for this section (h1, h2, h3, etc.). This values is derived from len(ast.Annotations.Path)
+	// and smoothed such that subsequent section only defer by +/- 1
+	Depth int
+	// H represent the markdown title symbol #, ##, ###, etc. (produced by strings.Repeat("#", depth))
+	H string
+	// Annotations is the raw metada provided by OPA compiler
 	Annotations *ast.Annotations
 }
 
+// Equal is only relevant for test ans asset that two ection are partially Equal
 func (s Section) Equal(s2 Section) bool {
 	if s.H == s2.H &&
 		s.Path == s2.Path &&
@@ -60,12 +72,12 @@ func (s Section) Equal(s2 Section) bool {
 
 // 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 guarantied. I couldn't find a way to call strings.Repeat inside go-template, this the title key is
+// 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
-func ConvertAnnotationsToSections(as ast.FlatAnnotationsRefSet) ([]Section, error) {
+func ConvertAnnotationsToSections(as ast.FlatAnnotationsRefSet) (Document, error) {
 
-	var s []Section
+	var d Document
 	var currentDepth = 0
 	var offset = 1
 
@@ -90,12 +102,13 @@ func ConvertAnnotationsToSections(as ast.FlatAnnotationsRefSet) ([]Section, erro
 		h := strings.Repeat("#", depth)
 		path := strings.TrimPrefix(entry.Path.String(), "data.")
 
-		s = append(s, Section{
+		d = append(d, Section{
+			Depth:       depth,
 			H:           h,
 			Path:        path,
 			Annotations: entry.Annotations,
 		})
 	}
 
-	return s, nil
+	return d, nil
 }

document/template.go

@@ -10,14 +10,16 @@ import (
 //go:embed resources/*
 var resources embed.FS
 
-// TemplateKind helps us to select where to find the template. It can either be embedded or on the host filesystem
+// TemplateKind helps us to select where to find the template. 
+// It can either be embedded or on the host filesystem
 type TemplateKind int
 
-const ( // iota is reset to 0
+const (
 	FS   TemplateKind = iota
 	FSYS              // fsys is used for embedded templates
 )
 
+// TemplateConfig represent the location of the template file(s)
 type TemplateConfig struct {
 	kind TemplateKind
 	path string
@@ -33,6 +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
 func WithTemplate(tpl string) RenderDocumentOption {
 	return func(c *TemplateConfig) {
 		c.kind = FS
@@ -42,22 +45,24 @@ func WithTemplate(tpl string) RenderDocumentOption {
 
 // RenderDocument takes a slice of Section and generate the markdown documentation either using the default
 // embedded template or the user provided template
-func RenderDocument(out io.Writer, s []Section, opts ...RenderDocumentOption) error {
+func RenderDocument(out io.Writer, d Document, opts ...RenderDocumentOption) error {
 	var tpl = NewTemplateConfig()
 
 	// Apply all the functional options to the template configurations
 	for _, opt := range opts {
 		opt(tpl)
 	}
 
-	err := renderTemplate(tpl, s, out)
+	err := renderTemplate(tpl, d, out)
 	if err != nil {
 		return err
 	}
 
 	return nil
 }
 
+// renderTemplate is an utility function to use go-template it handles fetching the template file(s)
+// whether they are embeded or on the host file system.
 func renderTemplate(tpl *TemplateConfig, args interface{}, out io.Writer) error {
 	var t *template.Template
 	var err error

document/template_test.go

@@ -38,11 +38,11 @@ func Test_generateDocument(t *testing.T) {
 				as, err := ParseRegoWithAnnotations(tt.testdata)
 				assert.NoError(t, err)
 
-				s, err := ConvertAnnotationsToSections(as)
+				d, err := ConvertAnnotationsToSections(as)
 				assert.NoError(t, err)
 
 				gotOut := &bytes.Buffer{}
-				err = RenderDocument(gotOut, s, tt.Option...)
+				err = RenderDocument(gotOut, d, tt.Option...)
 				if (err != nil) != tt.wantErr {
 					t.Errorf("GenVariableDoc() error = %v, wantErr %v", err, tt.wantErr)
 					return

go.mod

@@ -29,6 +29,7 @@ require (
 	github.com/spdx/tools-golang v0.5.5
 	github.com/spf13/cobra v1.8.1
 	github.com/spf13/viper v1.18.2
+	github.com/stretchr/testify v1.9.0
 	github.com/subosito/gotenv v1.6.0
 	github.com/tmccombs/hcl2json v0.3.1
 	golang.org/x/exp v0.0.0-20231006140011-7918f672742d