From 50e5f25329e689c5c4abfb792a41caffd59a8494 Mon Sep 17 00:00:00 2001
From: Micheal Wilkinson <micheal.wilkinson@createfuture.com>
Date: Fri, 20 Mar 2026 21:49:39 +0000
Subject: [PATCH] docs: add full godoc comments for vociferate API

---
 internal/vociferate/vociferate.go | 35 +++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/internal/vociferate/vociferate.go b/internal/vociferate/vociferate.go
index c98ecbd..936eb92 100644
--- a/internal/vociferate/vociferate.go
+++ b/internal/vociferate/vociferate.go
@@ -1,3 +1,9 @@
+// Package vociferate provides changelog-driven release preparation utilities.
+//
+// It updates version metadata, promotes the Unreleased changelog section into a
+// dated version section, recommends the next semantic version tag from pending
+// changelog entries, and normalizes changelog links when repository metadata is
+// available.
 package vociferate
 
 import (
@@ -21,9 +27,16 @@ var unreleasedHeadingRe = regexp.MustCompile(`(?m)^## \[Unreleased\](?:\([^\n)]*
 var releaseHeadingRe = regexp.MustCompile(`(?m)^## \[(\d+\.\d+\.\d+)\](?:\([^\n)]*\))? - `)
 
 type Options struct {
-	VersionFile    string
+	// VersionFile is the path to the file that stores the current version,
+	// relative to the repository root. When empty, release-version is used.
+	VersionFile string
+	// VersionPattern is a regular expression with exactly one capture group for
+	// extracting the current version from VersionFile.
+	// When empty, a line-oriented default matcher is used.
 	VersionPattern string
-	Changelog      string
+	// Changelog is the path to the changelog file, relative to the repository
+	// root. When empty, changelog.md is used.
+	Changelog string
 }
 
 type semver struct {
@@ -38,6 +51,14 @@ type resolvedOptions struct {
 	Changelog   string
 }
 
+// Prepare updates version state and promotes the Unreleased changelog notes
+// into a new release section.
+//
+// The version may be provided with or without a leading "v" and releaseDate
+// must use YYYY-MM-DD formatting. Prepare updates both the configured version
+// file and changelog, and enriches changelog headings with repository links
+// when repository metadata can be derived from CI environment variables or the
+// origin git remote.
 func Prepare(rootDir, version, releaseDate string, options Options) error {
 	normalizedVersion := strings.TrimPrefix(strings.TrimSpace(version), "v")
 	if normalizedVersion == "" {
@@ -65,6 +86,16 @@ func Prepare(rootDir, version, releaseDate string, options Options) error {
 	return nil
 }
 
+// RecommendedTag returns the next semantic release tag (for example, v1.2.3)
+// based on the current version and Unreleased changelog content.
+//
+// Bump rules are:
+//   - major: Unreleased contains a Breaking section or Removed entries
+//   - minor: Unreleased contains Added entries
+//   - patch: all other cases
+//
+// When no previous release is present in the changelog, the base version is
+// treated as 0.0.0.
 func RecommendedTag(rootDir string, options Options) (string, error) {
 	resolved, err := resolveOptions(options)
 	if err != nil {