From be68ebb9207d877234923cb445240295aca76e9b Mon Sep 17 00:00:00 2001 From: EliteMasterEric Date: Tue, 31 Mar 2026 22:24:40 -0400 Subject: [PATCH] Standardize doc style comments --- source/cpp/vm/tracy/TracyProfiler.hx | 52 +++++++++---------- source/funkin/audio/visualize/dsp/Complex.hx | 36 ++++++------- source/funkin/audio/visualize/dsp/FFT.hx | 44 ++++++++-------- .../funkin/audio/visualize/dsp/OffsetArray.hx | 20 +++---- source/funkin/audio/visualize/dsp/Signal.hx | 48 ++++++++--------- source/funkin/play/PlayState.hx | 4 +- .../play/cutscene/dialogue/Conversation.hx | 2 +- source/funkin/ui/options/OffsetMenu.hx | 4 +- source/funkin/util/tools/FloatTools.hx | 13 ++++- 9 files changed, 116 insertions(+), 107 deletions(-) diff --git a/source/cpp/vm/tracy/TracyProfiler.hx b/source/cpp/vm/tracy/TracyProfiler.hx index 0886492c0..842466ba9 100644 --- a/source/cpp/vm/tracy/TracyProfiler.hx +++ b/source/cpp/vm/tracy/TracyProfiler.hx @@ -19,68 +19,68 @@ enum abstract PlotFormatType(cpp.UInt8) from cpp.UInt8 to cpp.UInt8 extern class Native_TracyProfiler { /** - Mark a frame. Call this at the end of each frame loop. - **/ + * Mark a frame. Call this at the end of each frame loop. + */ @:native('::__hxcpp_tracy_framemark') public static function frameMark():Void; /** - Mark a named frame. Allows creating multiple frame sets for different timing categories. - Each unique name creates a separate frame set in the Tracy timeline. - **/ + * Mark a named frame. Allows creating multiple frame sets for different timing categories. + * Each unique name creates a separate frame set in the Tracy timeline. + */ @:native('::__hxcpp_tracy_framemark_named') public static function frameMarkNamed(_name:String):Void; /** - Mark the start of a discontinuous frame. Use for periodic work with gaps. - Must be paired with frameMarkEnd() using the same name. - **/ + * Mark the start of a discontinuous frame. Use for periodic work with gaps. + * Must be paired with frameMarkEnd() using the same name. + */ @:native('::__hxcpp_tracy_framemark_start') public static function frameMarkStart(_name:String):Void; /** - Mark the end of a discontinuous frame. Use for periodic work with gaps. - Must be paired with frameMarkStart() using the same name. - **/ + * Mark the end of a discontinuous frame. Use for periodic work with gaps. + * Must be paired with frameMarkStart() using the same name. + */ @:native('::__hxcpp_tracy_framemark_end') public static function frameMarkEnd(_name:String):Void; /** - Print a message into Tracy's log. - **/ + * Print a message into Tracy's log. + */ @:native('::__hxcpp_tracy_message') public static function message(_msg:String, ?_color:Int = 0x000000):Void; /** - Tracy can collect additional information about the profiled application, - which will be available in the trace description. - This can include data such as the source repository revision, - the application’s environment (dev/prod), etc. - **/ + * Tracy can collect additional information about the profiled application, + * which will be available in the trace description. + * This can include data such as the source repository revision, + * the application’s environment (dev/prod), etc. + */ @:native('::__hxcpp_tracy_message_app_info') public static function messageAppInfo(_info:String):Void; /** - Plot a named value to tracy. This will generate a graph in the profiler for you. - **/ + * Plot a named value to tracy. This will generate a graph in the profiler for you. + */ @:native('::__hxcpp_tracy_plot') public static function plot(_name:String, _val:cpp.Float32):Void; /** - Configure how values are plotted and displayed. - **/ + * Configure how values are plotted and displayed. + */ @:native('::__hxcpp_tracy_plot_config') public static function plotConfig(_name:String, _format:PlotFormatType, ?_step:Bool = false, ?_fill:Bool = false, ?_color:Int = 0x000000):Void; /** - Set a name for the current thread this function is called in. Supply an optional groupHint so threads become grouped in Tracy's UI. - **/ + * Set a name for the current thread this function is called in. Supply an optional groupHint so threads become grouped in Tracy's UI. + */ @:native('::__hxcpp_tracy_set_thread_name_and_group') public static function setThreadName(_name:String, ?_groupHint:Int = 1):Void; /** - Create a custom named scoped zone in your code. - **/ + * Create a custom named scoped zone in your code. + */ @:native('HXCPP_TRACY_ZONE') public static function zoneScoped(_name:String):Void; } diff --git a/source/funkin/audio/visualize/dsp/Complex.hx b/source/funkin/audio/visualize/dsp/Complex.hx index c88dc9706..11537831e 100644 --- a/source/funkin/audio/visualize/dsp/Complex.hx +++ b/source/funkin/audio/visualize/dsp/Complex.hx @@ -1,8 +1,8 @@ package funkin.audio.visualize.dsp; /** - Complex number representation. -**/ + * Complex number representation. + */ @:forward(real, imag) @:notNull @:pure @:nullSafety abstract Complex({ final real:Float; @@ -12,21 +12,21 @@ abstract Complex({ public inline function new(real:Float, imag:Float) this = {real: real, imag: imag}; /** - Makes a Complex number with the given Float as its real part and a zero imag part. - **/ + * Makes a Complex number with the given Float as its real part and a zero imag part. + */ @:from public static inline function fromReal(r:Float) return new Complex(r, 0); /** - Complex argument, in radians. - **/ + * Complex argument, in radians. + */ public var angle(get, never):Float; inline function get_angle() return Math.atan2(this.imag, this.real); /** - Complex module. - **/ + * Complex module. + */ public var magnitude(get, never):Float; inline function get_magnitude() return Math.sqrt(this.real * this.real + this.imag * this.imag); @@ -41,29 +41,29 @@ abstract Complex({ public inline function mult(rhs:Complex):Complex return new Complex(this.real * rhs.real - this.imag * rhs.imag, this.real * rhs.imag + this.imag * rhs.real); /** - Returns the complex conjugate, does not modify this object. - **/ + * Returns the complex conjugate, does not modify this object. + */ public inline function conj():Complex return new Complex(this.real, -this.imag); /** - Multiplication by a real factor, does not modify this object. - **/ + * Multiplication by a real factor, does not modify this object. + */ public inline function scale(k:Float):Complex return new Complex(this.real * k, this.imag * k); public inline function copy():Complex return new Complex(this.real, this.imag); /** - The imaginary unit. - **/ + * The imaginary unit. + */ public static final im = new Complex(0, 1); /** - The complex zero. - **/ + * The complex zero. + */ public static final zero = new Complex(0, 0); /** - Computes the complex exponential `e^(iw)`. - **/ + * Computes the complex exponential `e^(iw)`. + */ public static inline function exp(w:Float) return new Complex(Math.cos(w), Math.sin(w)); } diff --git a/source/funkin/audio/visualize/dsp/FFT.hx b/source/funkin/audio/visualize/dsp/FFT.hx index c7f622bb6..a9cd606e2 100644 --- a/source/funkin/audio/visualize/dsp/FFT.hx +++ b/source/funkin/audio/visualize/dsp/FFT.hx @@ -6,27 +6,27 @@ using funkin.audio.visualize.dsp.Signal; // these are only used for testing, down in FFT.main() /** - Fast/Finite Fourier Transforms. -**/ + * Fast/Finite Fourier Transforms. + */ @:nullSafety class FFT { /** - Computes the Discrete Fourier Transform (DFT) of a `Complex` sequence. - - If the input has N data points (N should be a power of 2 or padding will be added) - from a signal sampled at intervals of 1/Fs, the result will be a sequence of N - samples from the Discrete-Time Fourier Transform (DTFT) - which is Fs-periodic - - with a spacing of Fs/N Hz between them and a scaling factor of Fs. - **/ + * Computes the Discrete Fourier Transform (DFT) of a `Complex` sequence. + * + * If the input has N data points (N should be a power of 2 or padding will be added) + * from a signal sampled at intervals of 1/Fs, the result will be a sequence of N + * samples from the Discrete-Time Fourier Transform (DTFT) - which is Fs-periodic - + * with a spacing of Fs/N Hz between them and a scaling factor of Fs. + */ public static function fft(input:Array):Array return do_fft(input, false); /** - Like `fft`, but for a real (Float) sequence input. - - Since the input time signal is real, its frequency representation is - Hermitian-symmetric so we only return the positive frequencies. - **/ + * Like `fft`, but for a real (Float) sequence input. + * + * Since the input time signal is real, its frequency representation is + * Hermitian-symmetric so we only return the positive frequencies. + */ public static function rfft(input:Array):Array { final s = fft(input.map(Complex.fromReal)); @@ -34,12 +34,12 @@ class FFT } /** - Computes the Inverse DFT of a periodic input sequence. - - If the input contains N (a power of 2) DTFT samples, each spaced Fs/N Hz - from each other, the result will consist of N data points as sampled - from a time signal at intervals of 1/Fs with a scaling factor of 1/Fs. - **/ + * Computes the Inverse DFT of a periodic input sequence. + * + * If the input contains N (a power of 2) DTFT samples, each spaced Fs/N Hz + * from each other, the result will consist of N data points as sampled + * from a time signal at intervals of 1/Fs with a scaling factor of 1/Fs. + */ public static function ifft(input:Array):Array return do_fft(input, true); // Handles padding and scaling for forwards and inverse FFTs. @@ -102,8 +102,8 @@ class FFT } /** - Finds the power of 2 that is equal to or greater than the given natural. - **/ + * Finds the power of 2 that is equal to or greater than the given natural. + */ static function nextPow2(x:Int):Int { if (x < 2) return 1; diff --git a/source/funkin/audio/visualize/dsp/OffsetArray.hx b/source/funkin/audio/visualize/dsp/OffsetArray.hx index 42ea744d8..28186809e 100644 --- a/source/funkin/audio/visualize/dsp/OffsetArray.hx +++ b/source/funkin/audio/visualize/dsp/OffsetArray.hx @@ -1,10 +1,10 @@ package funkin.audio.visualize.dsp; /** - A view into an Array with an indexing offset. - - Usages include 1-indexed sequences or zero-centered buffers with negative indexing. -**/ + * A view into an Array with an indexing offset. + * + * Usages include 1-indexed sequences or zero-centered buffers with negative indexing. + */ @:forward(array, offset) @:nullSafety abstract OffsetArray({ final array:Array; @@ -24,8 +24,8 @@ abstract OffsetArray({ public inline function set(index:Int, value:T):Void this.array[index - this.offset] = value; /** - Iterates through items in their original order while providing the altered indexes as keys. - **/ + * Iterates through items in their original order while providing the altered indexes as keys. + */ public inline function keyValueIterator():KeyValueIterator return new OffsetArrayIterator(this.array, this.offset); @:from @@ -35,10 +35,10 @@ abstract OffsetArray({ inline function toArray() return this.array; /** - Makes a shifted version of the given `array`, where elements are in the - same order but shifted by `n` positions (to the right if positive and to - the left if negative) in **circular** fashion (no elements discarded). - **/ + * Makes a shifted version of the given `array`, where elements are in the + * same order but shifted by `n` positions (to the right if positive and to + * the left if negative) in **circular** fashion (no elements discarded). + */ public static function circShift(array:Array, n:Int):Array { if (n < 0) return circShift(array, array.length + n); diff --git a/source/funkin/audio/visualize/dsp/Signal.hx b/source/funkin/audio/visualize/dsp/Signal.hx index c7291bab9..619a65aaf 100644 --- a/source/funkin/audio/visualize/dsp/Signal.hx +++ b/source/funkin/audio/visualize/dsp/Signal.hx @@ -3,14 +3,14 @@ package funkin.audio.visualize.dsp; using Lambda; /** - Signal processing miscellaneous utilities. -**/ + * Signal processing miscellaneous utilities. + */ @:nullSafety class Signal { /** - Returns a smoothed version of the input array using a moving average. - **/ + * Returns a smoothed version of the input array using a moving average. + */ public static function smooth(y:Array, n:Int):Null> { if (n <= 0) @@ -35,11 +35,11 @@ class Signal } /** - Finds indexes of peaks in the order they appear in the input sequence. - - @param threshold Minimal peak height wrt. its neighbours, defaults to 0. - @param minHeight Minimal peak height wrt. the whole input, defaults to global minimum. - **/ + * Finds indexes of peaks in the order they appear in the input sequence. + * + * @param threshold Minimal peak height wrt. its neighbours, defaults to 0. + * @param minHeight Minimal peak height wrt. the whole input, defaults to global minimum. + */ public static function findPeaks(y:Array, ?threshold:Float, ?minHeight:Float):Array { threshold = threshold == null ? 0.0 : Math.abs(threshold); @@ -63,11 +63,11 @@ class Signal return peaks; } - /** - Returns the sum of all the elements of a given array. - - This function tries to minimize floating-point precision errors. - **/ + /*** + * Returns the sum of all the elements of a given array. + * + * This function tries to minimize floating-point precision errors. + */ public static function sum(array:Array):Float { // Neumaier's "improved Kahan-Babuska algorithm": @@ -87,27 +87,27 @@ class Signal } /** - Returns the average value of an array. - **/ + * Returns the average value of an array. + */ public static function mean(y:Array):Float return sum(y) / y.length; /** - Returns the global maximum. - **/ + * Returns the global maximum. + */ public static function max(y:Array):Float return y.fold(Math.max, y[0]); /** - Returns the global maximum's index. - **/ + * Returns the global maximum's index. + */ public static function maxi(y:Array):Int return y.foldi((yi, m, i) -> yi > y[m] ? i : m, 0); /** - Returns the global minimum. - **/ + * Returns the global minimum. + */ public static function min(y:Array):Float return y.fold(Math.min, y[0]); /** - Returns the global minimum's index. - **/ + * Returns the global minimum's index. + */ public static function mini(y:Array):Int return y.foldi((yi, m, i) -> yi < y[m] ? i : m, 0); } diff --git a/source/funkin/play/PlayState.hx b/source/funkin/play/PlayState.hx index 358e00b72..a5c9aa559 100644 --- a/source/funkin/play/PlayState.hx +++ b/source/funkin/play/PlayState.hx @@ -450,13 +450,13 @@ class PlayState extends MusicBeatSubState /** * Key press inputs which have been received but not yet processed. * These are encoded with an OS timestamp, so we can account for input latency. - **/ + */ var inputPressQueue:Array = []; /** * Key release inputs which have been received but not yet processed. * These are encoded with an OS timestamp, so we can account for input latency. - **/ + */ var inputReleaseQueue:Array = []; /** diff --git a/source/funkin/play/cutscene/dialogue/Conversation.hx b/source/funkin/play/cutscene/dialogue/Conversation.hx index 81d860a7d..205a80cf4 100644 --- a/source/funkin/play/cutscene/dialogue/Conversation.hx +++ b/source/funkin/play/cutscene/dialogue/Conversation.hx @@ -47,7 +47,7 @@ class Conversation extends FlxSpriteGroup implements IDialogueScriptedClass impl /** * The current line in the current entry in the dialogue. - * **/ + */ var currentDialogueLine:Int = 0; var currentDialogueLineCount(get, never):Int; diff --git a/source/funkin/ui/options/OffsetMenu.hx b/source/funkin/ui/options/OffsetMenu.hx index b3968f865..79aa61b45 100644 --- a/source/funkin/ui/options/OffsetMenu.hx +++ b/source/funkin/ui/options/OffsetMenu.hx @@ -90,13 +90,13 @@ class OffsetMenu extends Page /** * Key press inputs which have been received but not yet processed. * These are encoded with an OS timestamp, so we can account for input latency. - **/ + */ var inputPressQueue:Array = []; /** * Key release inputs which have been received but not yet processed. * These are encoded with an OS timestamp, so we can account for input latency. - **/ + */ var inputReleaseQueue:Array = []; /** diff --git a/source/funkin/util/tools/FloatTools.hx b/source/funkin/util/tools/FloatTools.hx index 168b2605b..7ac5cd9b0 100644 --- a/source/funkin/util/tools/FloatTools.hx +++ b/source/funkin/util/tools/FloatTools.hx @@ -8,6 +8,11 @@ class FloatTools { /** * Constrain a float between a minimum and maximum value. + * + * @param value The value to clamp. + * @param min The minimum value. + * @param max The maximum value. + * @return The clamped value. */ public static function clamp(value:Float, min:Float, max:Float):Float { @@ -15,8 +20,12 @@ class FloatTools } /** - Round a float to a certain number of decimal places. - **/ + * Round a float to a certain number of decimal places. + * + * @param number The number to round. + * @param precision The number of decimal places to round to. + * @return The rounded number. + */ public static function round(number:Float, precision:Int = 2):Float { number *= Math.pow(10, precision);