docs(lint): add AX usage examples

Co-Authored-By: Virgil <virgil@lethean.io>

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

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 = "."

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

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") {