From a567b72b18e43cb705ca99ddefe856ae498d2937 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Wed, 1 Apr 2026 12:24:29 +0000
Subject: [PATCH] docs(lint): add AX usage examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 pkg/lint/config.go         | 5 +++++
 pkg/lint/detect_project.go | 3 ++-
 pkg/lint/report.go         | 6 ++++--
 pkg/lint/scanner.go        | 4 ++--
 4 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/pkg/lint/config.go b/pkg/lint/config.go
index 1a9f1a4..07e6d80 100644
--- a/pkg/lint/config.go
+++ b/pkg/lint/config.go
@@ -47,6 +47,9 @@ type Schedule struct {
 }
 
 // DefaultConfig returns the RFC baseline config used when a repo has no local file yet.
+//
+//	cfg := lint.DefaultConfig()
+//	cfg.Output = "sarif"
 func DefaultConfig() LintConfig {
 	return LintConfig{
 		Lint: ToolGroups{
@@ -163,6 +166,8 @@ func LoadProjectConfig(projectPath string, override string) (LintConfig, string,
 }
 
 // ResolveSchedule returns a named schedule from the config.
+//
+//	schedule, err := lint.ResolveSchedule(cfg, "nightly")
 func ResolveSchedule(config LintConfig, name string) (*Schedule, error) {
 	if name == "" {
 		return nil, nil
diff --git a/pkg/lint/detect_project.go b/pkg/lint/detect_project.go
index 3f67295..6ea22d5 100644
--- a/pkg/lint/detect_project.go
+++ b/pkg/lint/detect_project.go
@@ -30,7 +30,8 @@ var projectLanguageByExtension = map[string]string{
 
 // Detect returns the project languages inferred from markers and file names.
 //
-//	langs := lint.Detect(".")
+//	lint.Detect(".")
+//	lint.Detect("/path/to/project")
 func Detect(path string) []string {
 	if path == "" {
 		path = "."
diff --git a/pkg/lint/report.go b/pkg/lint/report.go
index b9ec063..90616fb 100644
--- a/pkg/lint/report.go
+++ b/pkg/lint/report.go
@@ -18,6 +18,8 @@ type Summary struct {
 }
 
 // Summarise counts findings by severity.
+//
+//	summary := lint.Summarise(findings)
 func Summarise(findings []Finding) Summary {
 	s := Summary{
 		Total:      len(findings),
@@ -70,9 +72,9 @@ func WriteJSONL(w io.Writer, findings []Finding) error {
 	return nil
 }
 
-// WriteText writes findings in a human-readable format:
+// WriteText writes findings in a human-readable format.
 //
-//	file:line [severity] title (rule-id)
+//	lint.WriteText(os.Stdout, findings)
 func WriteText(w io.Writer, findings []Finding) {
 	for _, f := range findings {
 		message := f.Message
diff --git a/pkg/lint/scanner.go b/pkg/lint/scanner.go
index f901785..203e088 100644
--- a/pkg/lint/scanner.go
+++ b/pkg/lint/scanner.go
@@ -41,9 +41,9 @@ var defaultExcludes = []string{
 }
 
 // DetectLanguage returns the language identifier for a filename based on its extension.
-// Returns an empty string for unrecognised extensions.
 //
-//	lang := lint.DetectLanguage("main.go")
+//	lint.DetectLanguage("main.go")
+//	lint.DetectLanguage("Dockerfile")
 func DetectLanguage(filename string) string {
 	base := filepath.Base(filename)
 	if strings.HasPrefix(base, "Dockerfile") {