chore: cleanup doc comments

Author: ryanatkn

src/lib/changeset_generator.ts

@@ -95,9 +95,9 @@ const calculate_required_bump = (
  * and categorized list of breaking vs regular updates. Output format
  * matches changesets CLI for consistency.
  *
- * @param package_name package receiving the dependency updates
- * @param updates list of dependency changes with version info
- * @param bump_type required bump type (calculated from breaking changes)
+ * @param package_name - package receiving the dependency updates
+ * @param updates - list of dependency changes with version info
+ * @param bump_type - required bump type (calculated from breaking changes)
  * @returns markdown content ready to write to .changeset/*.md file
  */
 export const generate_changeset_content = (

src/lib/changeset_reader.ts

@@ -37,8 +37,8 @@ export interface ChangesetInfo {
  *
  * Summary of changes
  *
- * @param content changeset markdown with YAML frontmatter
- * @param filename optional filename for error reporting context
+ * @param content - changeset markdown with YAML frontmatter
+ * @param filename - optional filename for error reporting context
  * @returns parsed changeset info or null if invalid format
  */
 export const parse_changeset_content = (

src/lib/dependency_graph.ts

@@ -127,7 +127,7 @@ export class DependencyGraph {
 	 * Delegates to `@fuzdev/fuz_util/sort.js` for the sorting algorithm.
 	 * Throws if cycles detected.
 	 *
-	 * @param exclude_dev if true, excludes dev dependencies to break cycles.
+	 * @param exclude_dev - If true, excludes dev dependencies to break cycles.
 	 *   Publishing uses exclude_dev=true to handle circular dev deps.
 	 * @returns array of package names in dependency order (dependencies before dependents)
 	 * @throws {Error} if circular dependencies detected in included dependency types

src/lib/fetch_repo_data.ts

@@ -17,8 +17,8 @@ import type {LocalRepo} from './local_repo.js';
  * Error handling: Logs fetch failures but continues processing remaining repos.
  * Repos with failed fetches will have `null` for check_runs or pull_requests.
  *
- * @param delay milliseconds between API requests (default: 33ms)
- * @param cache optional cache from fuz_util's fetch.js for response memoization
+ * @param delay - milliseconds between API requests (default: 33ms)
+ * @param cache - optional cache from fuz_util's fetch.js for response memoization
  * @returns array of Repo objects with GitHub metadata attached
  */
 export const fetch_repo_data = async (

src/lib/fs_fetch_value_cache.ts

@@ -25,8 +25,8 @@ export interface FetchCache {
  * Uses `structuredClone` to track changes - only writes to disk if data modified.
  * Formatted with Prettier before writing for version control friendliness.
  *
- * @param name cache filename (without .json extension)
- * @param dir cache directory (defaults to `.gro/build/fetch/`)
+ * @param name - cache filename (without .json extension)
+ * @param dir - cache directory (defaults to `.gro/build/fetch/`)
  * @returns cache object with Map-based data and save() method
  */
 export const create_fs_fetch_value_cache = async (

src/lib/gitops_task_helpers.ts

@@ -53,10 +53,10 @@ export interface GetGitopsReadyOptions {
  * - Config `repos_dir` setting
  * - `DEFAULT_REPOS_DIR` constant
  *
- * @param options.git_ops for testing (defaults to real git operations)
- * @param options.npm_ops for testing (defaults to real npm operations)
- * @param options.parallel whether to load repos in parallel (default: true)
- * @param options.concurrency max concurrent repo loads (default: 5)
+ * @param options.git_ops - for testing (defaults to real git operations)
+ * @param options.npm_ops - for testing (defaults to real npm operations)
+ * @param options.parallel - whether to load repos in parallel (default: true)
+ * @param options.concurrency - max concurrent repo loads (default: 5)
  * @returns initialized config and fully loaded repos ready for operations
  * @throws {TaskError} if config loading or repo resolution fails
  */

src/lib/graph_validation.ts

@@ -32,9 +32,9 @@ export interface GraphValidationResult {
  * Shared utility for building dependency graph, detecting cycles, and computing publishing order.
  * This centralizes logic that was duplicated across multi_repo_publisher, publishing_plan, and gitops_analyze.
  *
- * @param options.throw_on_prod_cycles whether to throw an error if production cycles are detected (default: true)
- * @param options.log_cycles whether to log cycle information (default: true)
- * @param options.log_order whether to log publishing order (default: true)
+ * @param options.throw_on_prod_cycles - whether to throw an error if production cycles are detected (default: true)
+ * @param options.log_cycles - whether to log cycle information (default: true)
+ * @param options.log_order - whether to log publishing order (default: true)
  * @returns graph validation result with graph, publishing order, and detected cycles
  * @throws {TaskError} if production cycles detected and throw_on_prod_cycles is true
  */

src/lib/npm_install_helpers.ts

@@ -34,9 +34,9 @@ const is_etarget_error = (message: string, stderr: string): boolean => {
  * npm's local cache may still have stale "404" metadata. This healing
  * strategy clears the cache to force fresh metadata fetch.
  *
- * @param repo - The repository to install dependencies for
- * @param ops - Gitops operations (for dependency injection)
- * @param log - Optional logger
+ * @param repo - the repository to install dependencies for
+ * @param ops - gitops operations (for dependency injection)
+ * @param log - optional logger
  * @throws Error if install fails (with details about cache healing attempts)
  */
 export const install_with_cache_healing = async (

src/lib/npm_registry.ts

@@ -48,10 +48,10 @@ export const check_package_available = async (
  * Critical for multi-repo publishing: ensures published packages are available
  * before updating dependent packages.
  *
- * @param options.max_attempts max poll attempts (default 30)
- * @param options.initial_delay starting delay in ms (default 1000)
- * @param options.max_delay max delay between attempts (default 60000)
- * @param options.timeout total timeout in ms (default 300000 = 5min)
+ * @param options.max_attempts - max poll attempts (default 30)
+ * @param options.initial_delay - starting delay in ms (default 1000)
+ * @param options.max_delay - max delay between attempts (default 60000)
+ * @param options.timeout - total timeout in ms (default 300000 = 5min)
  * @throws {Error} if timeout reached or max attempts exceeded
  */
 export const wait_for_package = async (

src/lib/repo_ops.ts

@@ -83,8 +83,8 @@ export interface RepoPath {
  * Get repo paths from gitops config without full git sync.
  * Lighter weight than `get_gitops_ready()` - just resolves paths.
  *
- * @param config_path Path to gitops.config.ts (defaults to `./gitops.config.ts`)
- * @returns Array of repo info with name, path, and url
+ * @param config_path - path to gitops.config.ts (defaults to `./gitops.config.ts`)
+ * @returns array of repo info with name, path, and url
  */
 export const get_repo_paths = async (config_path?: string): Promise<Array<RepoPath>> => {
 	const resolved_config_path = resolve(config_path ?? GITOPS_CONFIG_PATH_DEFAULT);
@@ -152,8 +152,8 @@ export const should_exclude_path = (file_path: string, options?: WalkOptions): b
  * Walk files in a directory, respecting common exclusions.
  * Yields absolute paths to files (and optionally directories).
  *
- * @param dir Directory to walk
- * @param options Walk options for exclusions and filtering
+ * @param dir - directory to walk
+ * @param options - walk options for exclusions and filtering
  */
 export async function* walk_repo_files(
 	dir: string,