add js doc

scripts/analyze_benchmarks/extractor.ts

@@ -21,6 +21,11 @@ type BenchmarksJson = {
     [canisterName: string]: CanisterBenchmark;
 };
 
+/**
+ * Extracts benchmark entries from multiple files and groups them by version
+ * @param files Array of file paths to process
+ * @returns A record mapping version strings to arrays of benchmark entries
+ */
 export async function extractBenchmarksEntriesFromFiles(
     files: string[]
 ): Promise<Record<string, BenchmarkEntry[]>> {
@@ -32,6 +37,11 @@ export async function extractBenchmarksEntriesFromFiles(
     return groupEntriesByVersion(versionEntries);
 }
 
+/**
+ * Extracts benchmark entries from a single file
+ * @param file Path to the benchmark file
+ * @returns Array of tuples containing version and benchmark entry pairs
+ */
 async function extractBenchmarkEntries(
     file: string
 ): Promise<Array<[string, BenchmarkEntry]>> {
@@ -60,6 +70,11 @@ async function extractBenchmarkEntries(
     });
 }
 
+/**
+ * Groups benchmark entries by their version
+ * @param entries Array of version and benchmark entry pairs
+ * @returns A record mapping version strings to arrays of benchmark entries
+ */
 function groupEntriesByVersion(
     entries: Array<[string, BenchmarkEntry]>
 ): Record<string, BenchmarkEntry[]> {

scripts/analyze_benchmarks/file_finder.ts

@@ -1,6 +1,11 @@
 import { readdir, stat } from 'fs/promises';
 import { join } from 'path';
 
+/**
+ * Recursively finds all benchmark.json files in a directory and its subdirectories
+ * @param dir Directory path to search
+ * @returns Array of full paths to benchmark.json files
+ */
 export async function findBenchmarkFiles(dir: string): Promise<string[]> {
     if (dir.includes('node_modules')) {
         return [];
@@ -12,6 +17,12 @@ export async function findBenchmarkFiles(dir: string): Promise<string[]> {
     return itemResults.flat();
 }
 
+/**
+ * Processes a single item in a directory to determine if it's a benchmark file
+ * @param dir Parent directory path
+ * @param item Name of the item to process
+ * @returns Array of paths to benchmark files (empty if item is not a benchmark file)
+ */
 async function processDirectoryItem(
     dir: string,
     item: string

scripts/analyze_benchmarks/index.ts

@@ -7,6 +7,11 @@ import { findBenchmarkFiles } from './file_finder';
 import { reportResults, StableAndExperimentalStatistics } from './reporter';
 import { calculateVersionStatistics } from './statistics';
 
+/**
+ * Analyzes benchmarks for a specific version across stable and experimental examples
+ * @param targetVersion Version string to analyze
+ * @returns Statistics for both stable and experimental benchmarks
+ */
 async function analyzeBenchmarksForVersion(
     targetVersion: string
 ): Promise<StableAndExperimentalStatistics> {
@@ -35,6 +40,10 @@ async function analyzeBenchmarksForVersion(
     };
 }
 
+/**
+ * Runs the benchmark analysis for a specified version or current version
+ * @param specifiedVersion Optional version to analyze. If not provided, uses current package version
+ */
 function runBenchmarkAnalysis(specifiedVersion?: string): void {
     const versionToAnalyze = specifiedVersion ?? currentAzleVersion;
     console.info('Analyzing benchmarks...');

scripts/analyze_benchmarks/reporter.ts

@@ -14,6 +14,11 @@ export type StableAndExperimentalStatistics = {
 const RESULTS_FILE = join(AZLE_PACKAGE_PATH, 'benchmark_stats.json');
 const MARKDOWN_FILE = RESULTS_FILE.replace('.json', '.md');
 
+/**
+ * Reports benchmark results by updating JSON file and generating markdown report
+ * @param results Statistics for stable and experimental benchmarks
+ * @param version Version string for the results
+ */
 export async function reportResults(
     results: StableAndExperimentalStatistics,
     version: string
@@ -22,6 +27,10 @@ export async function reportResults(
     await outputMarkdownFromJson();
 }
 
+/**
+ * Reads the benchmark statistics from the JSON file
+ * @returns Record of version-keyed benchmark statistics
+ */
 export async function readBenchmarkJsonFile(): Promise<
     Record<string, Record<StableOrExperimental, Statistics>>
 > {

scripts/analyze_benchmarks/statistics.ts

@@ -17,6 +17,11 @@ const EFFICIENCY_WEIGHTS = {
     mean: 0.1
 } as const;
 
+/**
+ * Calculates statistics for a set of benchmark entries
+ * @param entries Array of benchmark entries to analyze
+ * @returns Statistical analysis of the benchmark data
+ */
 export function calculateVersionStatistics(
     entries: BenchmarkEntry[]
 ): Statistics {
@@ -27,6 +32,12 @@ export function calculateVersionStatistics(
     return calculateStatistics(instructions);
 }
 
+/**
+ * Calculates statistical measures for an array of instruction counts
+ * @param instructions Array of instruction counts
+ * @returns Statistical analysis including mean, median, standard deviation, etc.
+ * @throws Error if input array is empty or contains no valid instructions
+ */
 function calculateStatistics(instructions: number[]): Statistics {
     if (instructions.length === 0) {
         throw new Error('Cannot calculate statistics for empty array');
@@ -65,20 +76,35 @@ function calculateStatistics(instructions: number[]): Statistics {
     };
 }
 
-function calculateMean(instructions: readonly number[]): number {
+/**
+ * Calculates the mean of an array of numbers
+ * @param instructions Array of instruction counts
+ * @returns Arithmetic mean
+ */
+function calculateMean(instructions: number[]): number {
     return (
         instructions.reduce((acc, val) => acc + val, 0) / instructions.length
     );
 }
 
-function calculateMedian(sorted: readonly number[]): number {
+/**
+ * Calculates the median of a sorted array of numbers
+ * @param sorted Sorted array of numbers
+ * @returns Median value
+ */
+function calculateMedian(sorted: number[]): number {
     const mid = Math.floor(sorted.length / 2);
     return sorted.length % 2 === 0
         ? (sorted[mid - 1] + sorted[mid]) / 2
         : sorted[mid];
 }
 
-function calculateStandardDeviation(instructions: readonly number[]): number {
+/**
+ * Calculates the standard deviation of an array of numbers
+ * @param instructions Array of instruction counts
+ * @returns Standard deviation
+ */
+function calculateStandardDeviation(instructions: number[]): number {
     const mean = calculateMean(instructions);
     return Math.sqrt(
         instructions
@@ -87,6 +113,13 @@ function calculateStandardDeviation(instructions: readonly number[]): number {
     );
 }
 
+/**
+ * Calculates a weighted efficiency score based on min, median, and mean values
+ * @param min Minimum instruction count
+ * @param median Median instruction count
+ * @param mean Mean instruction count
+ * @returns Weighted efficiency score
+ */
 function calculateBaselineWeightEfficiencyScore(
     min: number,
     median: number,

scripts/analyze_benchmarks/validate_versions.ts

@@ -20,6 +20,14 @@ type BenchmarkEntry = {
 
 type BenchmarkData = Record<string, BenchmarkEntry>;
 
+/**
+ * Validates benchmark entries against expected versions
+ * @param filePath Path to the benchmark file
+ * @param entry Benchmark entry to validate
+ * @param expectedCurrentVersion Expected current version
+ * @param expectedPreviousVersion Expected previous version
+ * @returns Array of validation issues found
+ */
 function validateEntry(
     filePath: string,
     entry: BenchmarkEntry,
@@ -52,6 +60,13 @@ function validateEntry(
     ].filter(Boolean) as BenchmarkIssue[];
 }
 
+/**
+ * Validates versions in a benchmark file
+ * @param filePath Path to the benchmark file
+ * @param expectedCurrentVersion Expected current version
+ * @param expectedPreviousVersion Expected previous version
+ * @returns Array of validation issues found
+ */
 async function validateFile(
     filePath: string,
     expectedCurrentVersion: string,
@@ -70,6 +85,13 @@ async function validateFile(
     );
 }
 
+/**
+ * Validates versions across multiple benchmark files
+ * @param benchmarkFilePaths Array of paths to benchmark files
+ * @param expectedCurrentVersion Expected current version
+ * @param expectedPreviousVersion Expected previous version
+ * @returns Array of all validation issues found
+ */
 async function validateBenchmarkVersions(
     benchmarkFilePaths: string[],
     expectedCurrentVersion: string,