Add support for ignoring/deleting generated links

The generator takes an extra argument, through command-line or
environment variable, that allows to opt-out of documentation
generation. There is also the possibility to opt-in this deactivation on
a per-function basis, using the `--no-doc` argument on the directive.

This also changes the name of the directive, from `autometrics:doc` to
`autometrics:inst`, as now the directive doesn't always add
documentation to the functions it instruments. For backwards
compatibility, the `doc` attribute is still accepted, and will be
removed in a later version.

Closes #38

cmd/autometrics/main.go

@@ -23,6 +23,7 @@ type args struct {
 	PrometheusUrl        string `arg:"--prom_url,env:AM_PROMETHEUS_URL" placeholder:"PROMETHEUS_URL" default:"http://localhost:9090" help:"Base URL of the Prometheus instance to generate links to."`
 	UseOtel              bool   `arg:"--otel" default:"false" help:"Use OpenTelemetry client library to instrument code instead of default Prometheus."`
 	AllowCustomLatencies bool   `arg:"--custom-latency" default:"false" help:"Allow non-default latencies to be used in latency-based SLOs."`
+	DisableDocGeneration bool   `arg:"--no-doc,env:AM_NO_DOCGEN" default:"false" help:"Disable documentation links generation for all instrumented functions. Has the same effect as --no-doc in the //autometrics:inst directive."`
 }
 
 func (args) Version() string {
@@ -63,7 +64,12 @@ func main() {
 		implementation = autometrics.OTEL
 	}
 
-	ctx, err := internal.NewGeneratorContext(implementation, args.PrometheusUrl, args.AllowCustomLatencies)
+	ctx, err := internal.NewGeneratorContext(
+		implementation,
+		args.PrometheusUrl,
+		args.AllowCustomLatencies,
+		args.DisableDocGeneration,
+	)
 	if err != nil {
 		log.Fatalf("error initialising autometrics context: %s", err)
 	}

internal/autometrics/ctx.go

@@ -7,19 +7,35 @@ import (
 	"github.com/autometrics-dev/autometrics-go/pkg/autometrics"
 )
 
+// GeneratorContext contains the complete command-line and environment context from the generator invocation.
+//
+// This context contains all the information necessary to properly process the `autometrics` directives over
+// each instrumented function in the file.
 type GeneratorContext struct {
-	RuntimeCtx             autometrics.Context
-	FuncCtx                GeneratorFunctionContext
-	Implementation         autometrics.Implementation
+	// RuntimeCtx holds the runtime context to build from in the generated code.
+	RuntimeCtx autometrics.Context
+	// FuncCtx holds the function specific information for the detected autometrics directive.
+	//
+	// Notably, it contains all the data relative to the parsing of the arguments in the directive.
+	FuncCtx GeneratorFunctionContext
+	// Implementation is the metrics library we expect to use in the instrumented code.
+	Implementation autometrics.Implementation
+	// DocumentationGenerator is the generator to use to generate comments.
 	DocumentationGenerator AutometricsLinkCommentGenerator
-	AllowCustomLatencies   bool
+	// Allow the autometrics directive to have latency targets outside the default buckets.
+	AllowCustomLatencies bool
+	// Flag to disable/remove the documentation links when calling the generator.
+	//
+	// This can be set in the command for the generator or through the environment.
+	DisableDocGeneration bool
 }
 
 type GeneratorFunctionContext struct {
 	CommentIndex   int
 	FunctionName   string
 	ModuleName     string
 	ImplImportName string
+	DisableDocGeneration bool
 }
 
 func (c *GeneratorContext) ResetFuncCtx() {
@@ -32,10 +48,11 @@ func (c *GeneratorContext) SetCommentIdx(i int) {
 	c.FuncCtx.CommentIndex = i
 }
 
-func NewGeneratorContext(implementation autometrics.Implementation, prometheusUrl string, allowCustomLatencies bool) (GeneratorContext, error) {
+func NewGeneratorContext(implementation autometrics.Implementation, prometheusUrl string, allowCustomLatencies, disableDocGeneration bool) (GeneratorContext, error) {
 	ctx := GeneratorContext{
 		Implementation:       implementation,
 		AllowCustomLatencies: allowCustomLatencies,
+		DisableDocGeneration: disableDocGeneration,
 		RuntimeCtx:           autometrics.NewContext(),
 		FuncCtx:              GeneratorFunctionContext{},
 	}

internal/generate/generate.go

@@ -23,13 +23,14 @@ const (
 	SuccessObjArgument = "--success-target"
 	LatencyMsArgument  = "--latency-ms"
 	LatencyObjArgument = "--latency-target"
+	NoDocArgument      = "--no-doc"
 
 	AmPromPackage = "\"github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus\""
 	AmOtelPackage = "\"github.com/autometrics-dev/autometrics-go/pkg/autometrics/otel\""
 )
 
 // TransformFile takes a file path and generates the documentation
-// for the `//autometrics:doc` functions.
+// for the `//autometrics:inst` functions.
 //
 // It also replaces the file in place.
 func TransformFile(ctx internal.GeneratorContext, path, moduleName string) error {
@@ -65,7 +66,7 @@ func TransformFile(ctx internal.GeneratorContext, path, moduleName string) error
 }
 
 // GenerateDocumentationAndInstrumentation takes the raw source code from a file and generates
-// the documentation for the `//autometrics:doc` functions.
+// the documentation for the `//autometrics:inst` functions.
 //
 // It returns the new source code with augmented documentation.
 func GenerateDocumentationAndInstrumentation(ctx internal.GeneratorContext, sourceCode, moduleName string) (string, error) {
@@ -185,8 +186,12 @@ func GenerateDocumentationAndInstrumentation(ctx internal.GeneratorContext, sour
 			listIndex := ctx.FuncCtx.CommentIndex
 			if listIndex >= 0 {
 				// Insert comments
-				autometricsComment := generateAutometricsComment(ctx)
-				funcDeclaration.Decorations().Start.Replace(insertComments(docComments, listIndex, autometricsComment)...)
+				if !ctx.DisableDocGeneration && !ctx.FuncCtx.DisableDocGeneration {
+					autometricsComment := generateAutometricsComment(ctx)
+					funcDeclaration.Decorations().Start.Replace(insertComments(docComments, listIndex, autometricsComment)...)
+				} else {
+					funcDeclaration.Decorations().Start.Replace(docComments...)
+				}
 
 				// defer statement
 				firstStatement := funcDeclaration.Body.List[0]
@@ -351,6 +356,9 @@ func buildAutometricsDeferStatement(ctx internal.GeneratorContext, secondVar str
 func parseAutometricsFnContext(ctx *internal.GeneratorContext, commentGroup []string) error {
 	for i, comment := range commentGroup {
 		if args, found := cutPrefix(comment, "//autometrics:"); found {
+			if !strings.Contains(comment, "autometrics:doc") && !strings.Contains(comment, "autometrics:inst") {
+				return fmt.Errorf("invalid directive comment '%s': only '//autometrics:doc' and '//autometrics:inst' are allowed.", comment)
+			}
 			ctx.FuncCtx.CommentIndex = i
 			ctx.RuntimeCtx = autometrics.NewContext()
 
@@ -475,6 +483,9 @@ func parseAutometricsFnContext(ctx *internal.GeneratorContext, commentGroup []st
 					}
 					// Advance past the "value"
 					tokenIndex = tokenIndex + 1
+				case token == NoDocArgument:
+					ctx.FuncCtx.DisableDocGeneration = true
+					tokenIndex = tokenIndex + 1
 				default:
 					// Advance past the "value"
 					tokenIndex = tokenIndex + 1