Relocate comments to rego.Function.Description in preparation for auto-generating documentation.

[evankanderson]

Summary

This moves all the large, helpful Golang comments into the Function.Description field. The next step will be to convert all the existing func(*interfaces.Result) func(*rego.Rego) functions to entries in a list, like so:

type vfsFunc(billy.Filesystem) rego.BuiltinDyn

type FunctionEntry struct {
  // The rego function definition (metadata)
  decl *rego.Function

  // Only one of the following should be set:

  // A bare function implementation which does not need a vfs
  bareImpl rego.BuiltinDyn
  // A function implementation that should receive the current vfs
  vfsImpl  vfsFunc
  // A function implementation that sohuld receive the pre-change vfs
  baseImpl vfsFunc
}

In that PR, we can then convert the existing initialization to:

var MinderRegoLib = []FunctionEntry{
  FileExists,
  ...
}

var FileExists = FunctionEntry{
  decl: &rego.Function{
    ...
  },
  vfsImpl: fsExists,
}
...

Which allows us to iterate over MinderRegoLib, extract the decl.Description (and decl.Name) to generate a markdown file of all the custom functions in the Minder Rego runtime. We can then include these in the reference section of the documentation.

Change Type

Mark the type of change your PR introduces:

• Bug fix (resolves an issue without affecting existing features)
• Feature (adds new functionality without breaking changes)
• Breaking change (may impact existing functionalities or require documentation updates)
• Documentation (updates or additions to documentation)
• Refactoring or test improvements (no bug fixes or new functionality)

Testing

Existing unit tests.

Review Checklist:

• Reviewed my own code for quality and clarity.
• Added comments to complex or tricky code sections.
• Updated any affected documentation.
• Included tests that validate the fix or feature.
• Checked that related changes are merged.

[coveralls]

coverage: 56.836% (+0.1%) from 56.687%
when pulling 6c961a8 on evankanderson:doc-functions
into 0f726c7 on mindersec:main.

[JAORMX]

Lovely!