From 0e9837a75aacdd1a030aab2e99bbb73c82085457 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Mon, 19 Jan 2026 10:27:53 +0800 Subject: [PATCH] doc: add docstring for sonnet --- BallanceTasSonnet/src/lib.rs | 170 +++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) diff --git a/BallanceTasSonnet/src/lib.rs b/BallanceTasSonnet/src/lib.rs index ddef8af..d093aaa 100644 --- a/BallanceTasSonnet/src/lib.rs +++ b/BallanceTasSonnet/src/lib.rs @@ -3,12 +3,14 @@ use pyo3::prelude::*; pub(crate) mod wrapped; #[pymodule(name = "_blctas")] +/// Provides functionality for handling Ballance TAS works. mod blctas { #[pymodule_export] use super::tasfile; } #[pymodule(submodule)] +/// Provides functionality for handling Ballance TAS files loading, saving and editing. mod tasfile { use pyo3::{exceptions::PyRuntimeError, prelude::*}; use crate::wrapped::tasfile::{ @@ -23,24 +25,34 @@ mod tasfile { #[pyclass(eq, eq_int)] #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] + /// Represents the different keys that can be pressed in a TAS frame. enum TasKey { #[pyo3(name = "KEY_UP")] + /// Up arrow key KeyUp, #[pyo3(name = "KEY_DOWN")] + /// Down arrow key KeyDown, #[pyo3(name = "KEY_LEFT")] + /// Left arrow key KeyLeft, #[pyo3(name = "KEY_RIGHT")] + /// Right arrow key KeyRight, #[pyo3(name = "KEY_SHIFT")] + /// Shift key KeyShift, #[pyo3(name = "KEY_SPACE")] + /// Spacebar key KeySpace, #[pyo3(name = "KEY_Q")] + /// Q key KeyQ, #[pyo3(name = "KEY_ESC")] + /// Escape key KeyEsc, #[pyo3(name = "KEY_ENTER")] + /// Enter key KeyEnter, } @@ -62,6 +74,8 @@ mod tasfile { #[pyclass] #[derive(Debug)] + /// Represents a TAS file containing a sequence of frames. + /// Each frame contains key press information and delta time for Ballance gameplay. struct TasFile { inner: RsTasFile } @@ -70,14 +84,23 @@ mod tasfile { impl TasFile { // region: Status + /// Clears all frames from the TAS file. fn clear(&mut self) -> PyResult<()> { Ok(self.inner.clear()) } + /// Gets the number of frames in the TAS file. + /// + /// Returns: + /// The count of frames in the TAS file. fn get_count(&self) -> PyResult { Ok(self.inner.get_count()) } + /// Checks if the TAS file is empty (contains no frames). + /// + /// Returns: + /// True if the TAS file is empty, False otherwise. fn is_empty(&self) -> PyResult { Ok(self.inner.is_empty()) } @@ -86,26 +109,80 @@ mod tasfile { // region: Single Operation + /// Gets the delta time of a frame at the specified index. + /// + /// Args: + /// index: The index of the frame to get the delta time from. + /// + /// Returns: + /// The delta time value of the frame at the specified index. + /// + /// Raises: + /// RuntimeError: If the index is out of range. fn get_delta_time(&self, index: usize) -> PyResult { Ok(self.inner.visit(index)?.get_delta_time()) } + /// Sets the delta time of a frame at the specified index. + /// + /// Args: + /// index: The index of the frame to set the delta time for. + /// delta_time: The new delta time value to set. + /// + /// Raises: + /// RuntimeError: If the index is out of range. fn set_delta_time(&mut self, index: usize, delta_time: f32) -> PyResult<()> { Ok(self.inner.visit_mut(index)?.set_delta_time(delta_time)) } + /// Checks if a specific key is pressed in the frame at the specified index. + /// + /// Args: + /// index: The index of the frame to check. + /// key: The key to check for press status. + /// + /// Returns: + /// True if the key is pressed, False otherwise. + /// + /// Raises: + /// RuntimeError: If the index is out of range. fn is_key_pressed(&self, index: usize, key: TasKey) -> PyResult { Ok(self.inner.visit(index)?.is_key_pressed(key.into())) } + /// Sets the press status of a specific key in the frame at the specified index. + /// + /// Args: + /// index: The index of the frame to modify. + /// key: The key to set the press status for. + /// pressed: True to press the key, False to release it. + /// + /// Raises: + /// RuntimeError: If the index is out of range. fn set_key_pressed(&mut self, index: usize, key: TasKey, pressed: bool) -> PyResult<()> { Ok(self.inner.visit_mut(index)?.set_key_pressed(key.into(), pressed)) } + /// Flips the press status of a specific key in the frame at the specified index. + /// If the key was pressed, it becomes released; if it was released, it becomes pressed. + /// + /// Args: + /// index: The index of the frame to modify. + /// key: The key to flip the press status for. + /// + /// Raises: + /// RuntimeError: If the index is out of range. fn flip_key_pressed(&mut self, index: usize, key: TasKey) -> PyResult<()> { Ok(self.inner.visit_mut(index)?.flip_key_pressed(key.into())) } + /// Clears all key presses in the frame at the specified index, setting all keys to released state. + /// + /// Args: + /// index: The index of the frame to clear key presses for. + /// + /// Raises: + /// RuntimeError: If the index is out of range. fn clear_key_pressed(&mut self, index: usize) -> PyResult<()> { Ok(self.inner.visit_mut(index)?.clear_key_pressed()) } @@ -114,6 +191,17 @@ mod tasfile { // region: Batchly Operation + /// Sets the delta time for a range of frames from index_from to index_to (inclusive). + /// This is a batch operation that modifies multiple frames in one call, which is more + /// efficient than calling set_delta_time individually on each frame. + /// + /// Args: + /// index_from: The starting index (inclusive) of the range to modify. + /// index_to: The ending index (inclusive) of the range to modify. + /// delta_time: The new delta time value to set for all frames in the range. + /// + /// Raises: + /// RuntimeError: If either index is out of range or if index_to < index_from. fn batchly_set_delta_time(&mut self, index_from: usize, index_to: usize, delta_time: f32) -> PyResult<()> { for frame in self.inner.batchly_visit_mut(index_from, index_to)? { frame.set_delta_time(delta_time); @@ -121,6 +209,18 @@ mod tasfile { Ok(()) } + /// Sets the press status of a specific key for a range of frames from index_from to index_to (inclusive). + /// This is a batch operation that modifies multiple frames in one call, which is more + /// efficient than calling set_key_pressed individually on each frame. + /// + /// Args: + /// index_from: The starting index (inclusive) of the range to modify. + /// index_to: The ending index (inclusive) of the range to modify. + /// key: The key to set the press status for. + /// pressed: True to press the key, False to release it for all frames in the range. + /// + /// Raises: + /// RuntimeError: If either index is out of range or if index_to < index_from. fn batchly_set_key_pressed(&mut self, index_from: usize, index_to: usize, key: TasKey, pressed: bool) -> PyResult<()> { for frame in self.inner.batchly_visit_mut(index_from, index_to)? { frame.set_key_pressed(key.into(), pressed); @@ -128,6 +228,17 @@ mod tasfile { Ok(()) } + /// Flips the press status of a specific key for a range of frames from index_from to index_to (inclusive). + /// This is a batch operation that modifies multiple frames in one call, which is more + /// efficient than calling flip_key_pressed individually on each frame. + /// + /// Args: + /// index_from: The starting index (inclusive) of the range to modify. + /// index_to: The ending index (inclusive) of the range to modify. + /// key: The key to flip the press status for in all frames in the range. + /// + /// Raises: + /// RuntimeError: If either index is out of range or if index_to < index_from. fn batchly_flip_key_pressed(&mut self, index_from: usize, index_to: usize, key: TasKey) -> PyResult<()> { for frame in self.inner.batchly_visit_mut(index_from, index_to)? { frame.flip_key_pressed(key.into()); @@ -135,6 +246,17 @@ mod tasfile { Ok(()) } + /// Clears all key presses for a range of frames from index_from to index_to (inclusive). + /// This sets all keys to the released state for all frames in the range. + /// This is a batch operation that modifies multiple frames in one call, which is more + /// efficient than calling clear_key_pressed individually on each frame. + /// + /// Args: + /// index_from: The starting index (inclusive) of the range to modify. + /// index_to: The ending index (inclusive) of the range to modify. + /// + /// Raises: + /// RuntimeError: If either index is out of range or if index_to < index_from. fn batchly_clear_key_pressed(&mut self, index_from: usize, index_to: usize) -> PyResult<()> { for frame in self.inner.batchly_visit_mut(index_from, index_to)? { frame.clear_key_pressed(); @@ -146,16 +268,38 @@ mod tasfile { // region: Modify + /// Appends a specified number of frames with the given delta time to the end of the TAS file. + /// + /// Args: + /// count: The number of frames to append. + /// delta_time: The delta time value for the new frames. fn append(&mut self, count: usize, delta_time: f32) -> PyResult<()> { let frames = vec![RsTasFrame::with_delta_time(delta_time); count]; Ok(self.inner.append(&frames)) } + /// Inserts a specified number of frames with the given delta time at the specified index. + /// + /// Args: + /// index: The position at which to insert the new frames. + /// count: The number of frames to insert. + /// delta_time: The delta time value for the new frames. + /// + /// Raises: + /// RuntimeError: If the index is out of range. fn insert(&mut self, index: usize, count: usize, delta_time: f32) -> PyResult<()> { let frames = vec![RsTasFrame::with_delta_time(delta_time); count]; Ok(self.inner.insert(index, &frames)?) } + /// Removes frames from the TAS file within the specified range (inclusive). + /// + /// Args: + /// index_from: The starting index (inclusive) of the range to remove. + /// index_to: The ending index (inclusive) of the range to remove. + /// + /// Raises: + /// RuntimeError: If either index is out of range or if index_to < index_from. fn remove(&mut self, index_from: usize, index_to: usize) -> PyResult<()> { Ok(self.inner.remove(index_from, index_to)?) } @@ -164,16 +308,42 @@ mod tasfile { } #[pyfunction] + /// Creates a new TAS file with a specified number of frames, all having the same delta time. + /// + /// Args: + /// count: The number of frames to create in the new TAS file. + /// delta_time: The delta time value for all frames in the new TAS file. + /// + /// Returns: + /// A new TasFile instance with the specified number of frames. fn create(count: usize, delta_time: f32) -> PyResult { Ok(TasFile { inner: RsTasFile::new(vec![RsTasFrame::with_delta_time(delta_time); count]) }) } #[pyfunction] + /// Loads a TAS file from disk. + /// + /// Args: + /// filename: The path to the TAS file to load. + /// + /// Returns: + /// A TasFile instance loaded from the specified file. + /// + /// Raises: + /// RuntimeError: If the file cannot be loaded or is invalid. fn load(filename: &str) -> PyResult { Ok(TasFile { inner: RsTasFile::load(filename)? }) } #[pyfunction] + /// Saves a TAS file to disk. + /// + /// Args: + /// file: The TasFile instance to save. + /// filename: The path where the TAS file should be saved. + /// + /// Raises: + /// RuntimeError: If the file cannot be saved. fn save(file: &TasFile, filename: &str) -> PyResult<()> { Ok(file.inner.save(filename)?) }