doc: update doc style for sonnet

BallanceTasSonnet/python/blctas/ballance.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+
+def launch_game(game_path: Path) -> None:
+    """
+    Launch given Ballance game and wait until it quit.
+    """
+    pass
+

BallanceTasSonnet/python/blctas/tasfile.py

@@ -1,4 +1,4 @@
-import _blctas.tasfile
+import _blctas # type: ignore
 
-if __name__ == '__main__':
+from _blctas.tasfile import TasKey, TasFile # type: ignore
-    print(dir(_blctas))
+from _blctas.tasfile import create, load, save # type: ignore

BallanceTasSonnet/rust/src/lib.rs

@@ -75,6 +75,9 @@ mod tasfile {
     #[pyclass]
     #[derive(Debug)]
     /// Represents a TAS file containing a sequence of frames.
+    /// 
+    /// This class provides methods for manipulating TAS files including adding, removing,
+    /// modifying frames, and getting/setting key press states.
     /// Each frame contains key press information and delta time for Ballance gameplay.
     struct TasFile {
         inner: RsTasFile
@@ -85,22 +88,28 @@ mod tasfile {
         // region: Status
 
         /// Clears all frames from the TAS file.
+        /// 
+        /// .. note::
+        ///    This operation is irreversible and will remove all frames from the TAS file.
+        /// 
+        /// :returns: None
+        /// :rtype: None
         fn clear(&mut self) -> PyResult<()> {
             Ok(self.inner.clear())
         }
 
         /// Gets the number of frames in the TAS file.
         /// 
-        /// Returns:
+        /// :returns: The count of frames in the TAS file.
-        ///     The count of frames in the TAS file.
+        /// :rtype: int
         fn get_count(&self) -> PyResult<usize> {
             Ok(self.inner.get_count())
         }
 
         /// Checks if the TAS file is empty (contains no frames).
         /// 
-        /// Returns:
+        /// :returns: True if the TAS file is empty, False otherwise.
-        ///     True if the TAS file is empty, False otherwise.
+        /// :rtype: bool
         fn is_empty(&self) -> PyResult<bool> {
             Ok(self.inner.is_empty())
         }
@@ -111,54 +120,52 @@ mod tasfile {
 
         /// Gets the delta time of a frame at the specified index.
         /// 
-        /// Args:
+        /// :param index: The index of the frame to get the delta time from.
-        ///     index: The index of the frame to get the delta time from.
+        /// :type index: int
-        /// 
+        /// :returns: The delta time value of the frame at the specified index.
-        /// Returns:
+        /// :rtype: float
-        ///     The delta time value of the frame at the specified index.
+        /// :raises RuntimeError: If the index is out of range.
-        /// 
-        /// Raises:
-        ///     RuntimeError: If the index is out of range.
         fn get_delta_time(&self, index: usize) -> PyResult<f32> {
             Ok(self.inner.visit(index)?.get_delta_time())
         }
 
         /// Sets the delta time of a frame at the specified index.
         /// 
-        /// Args:
+        /// :param index: The index of the frame to set the delta time for.
-        ///     index: The index of the frame to set the delta time for.
+        /// :type index: int
-        ///     delta_time: The new delta time value to set.
+        /// :param delta_time: The new delta time value to set.
-        /// 
+        /// :type delta_time: float
-        /// Raises:
+        /// :returns: None
-        ///     RuntimeError: If the index is out of range.
+        /// :rtype: None
+        /// :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:
+        /// :param index: The index of the frame to check.
-        ///     index: The index of the frame to check.
+        /// :type index: int
-        ///     key: The key to check for press status.
+        /// :param key: The key to check for press status.
-        /// 
+        /// :type key: TasKey
-        /// Returns:
+        /// :returns: True if the key is pressed, False otherwise.
-        ///     True if the key is pressed, False otherwise.
+        /// :rtype: bool
-        /// 
+        /// :raises RuntimeError: If the index is out of range.
-        /// Raises:
-        ///     RuntimeError: If the index is out of range.
         fn is_key_pressed(&self, index: usize, key: TasKey) -> PyResult<bool> {
             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:
+        /// :param index: The index of the frame to modify.
-        ///     index: The index of the frame to modify.
+        /// :type index: int
-        ///     key: The key to set the press status for.
+        /// :param key: The key to set the press status for.
-        ///     pressed: True to press the key, False to release it.
+        /// :type key: TasKey
-        /// 
+        /// :param pressed: True to press the key, False to release it.
-        /// Raises:
+        /// :type pressed: bool
-        ///     RuntimeError: If the index is out of range.
+        /// :returns: None
+        /// :rtype: None
+        /// :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))
         }
@@ -166,23 +173,24 @@ mod tasfile {
         /// 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:
+        /// :param index: The index of the frame to modify.
-        ///     index: The index of the frame to modify.
+        /// :type index: int
-        ///     key: The key to flip the press status for.
+        /// :param key: The key to flip the press status for.
-        /// 
+        /// :type key: TasKey
-        /// Raises:
+        /// :returns: None
-        ///     RuntimeError: If the index is out of range.
+        /// :rtype: None
+        /// :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:
+        /// :param index: The index of the frame to clear key presses for.
-        ///     index: The index of the frame to clear key presses for.
+        /// :type index: int
-        /// 
+        /// :returns: None
-        /// Raises:
+        /// :rtype: None
-        ///     RuntimeError: If the index is out of range.
+        /// :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())
         }
@@ -195,13 +203,18 @@ mod tasfile {
         /// 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:
+        /// .. note::
-        ///     index_from: The starting index (inclusive) of the range to modify.
+        ///    This function exists to reduce Python FFI call overhead during iteration.
-        ///     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:
+        /// :param index_from: The starting index (inclusive) of the range to modify.
-        ///     RuntimeError: If either index is out of range or if index_to < index_from.
+        /// :type index_from: int
+        /// :param index_to: The ending index (inclusive) of the range to modify.
+        /// :type index_to: int
+        /// :param delta_time: The new delta time value to set for all frames in the range.
+        /// :type delta_time: float
+        /// :returns: None
+        /// :rtype: None
+        /// :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);
@@ -213,14 +226,20 @@ mod tasfile {
         /// 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:
+        /// .. note::
-        ///     index_from: The starting index (inclusive) of the range to modify.
+        ///    This function exists to reduce Python FFI call overhead during iteration.
-        ///     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:
+        /// :param index_from: The starting index (inclusive) of the range to modify.
-        ///     RuntimeError: If either index is out of range or if index_to < index_from.
+        /// :type index_from: int
+        /// :param index_to: The ending index (inclusive) of the range to modify.
+        /// :type index_to: int
+        /// :param key: The key to set the press status for.
+        /// :type key: TasKey
+        /// :param pressed: True to press the key, False to release it for all frames in the range.
+        /// :type pressed: bool
+        /// :returns: None
+        /// :rtype: None
+        /// :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);
@@ -232,13 +251,18 @@ mod tasfile {
         /// 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:
+        /// .. note::
-        ///     index_from: The starting index (inclusive) of the range to modify.
+        ///    This function exists to reduce Python FFI call overhead during iteration.
-        ///     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:
+        /// :param index_from: The starting index (inclusive) of the range to modify.
-        ///     RuntimeError: If either index is out of range or if index_to < index_from.
+        /// :type index_from: int
+        /// :param index_to: The ending index (inclusive) of the range to modify.
+        /// :type index_to: int
+        /// :param key: The key to flip the press status for in all frames in the range.
+        /// :type key: TasKey
+        /// :returns: None
+        /// :rtype: None
+        /// :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());
@@ -251,12 +275,16 @@ mod tasfile {
         /// 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:
+        /// .. note::
-        ///     index_from: The starting index (inclusive) of the range to modify.
+        ///    This function exists to reduce Python FFI call overhead during iteration.
-        ///     index_to: The ending index (inclusive) of the range to modify.
         /// 
-        /// Raises:
+        /// :param index_from: The starting index (inclusive) of the range to modify.
-        ///     RuntimeError: If either index is out of range or if index_to < index_from.
+        /// :type index_from: int
+        /// :param index_to: The ending index (inclusive) of the range to modify.
+        /// :type index_to: int
+        /// :returns: None
+        /// :rtype: None
+        /// :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();
@@ -270,9 +298,12 @@ mod tasfile {
 
         /// Appends a specified number of frames with the given delta time to the end of the TAS file.
         /// 
-        /// Args:
+        /// :param count: The number of frames to append.
-        ///     count: The number of frames to append.
+        /// :type count: int
-        ///     delta_time: The delta time value for the new frames.
+        /// :param delta_time: The delta time value for the new frames.
+        /// :type delta_time: float
+        /// :returns: None
+        /// :rtype: None
         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))
@@ -280,13 +311,19 @@ mod tasfile {
         
         /// Inserts a specified number of frames with the given delta time at the specified index.
         /// 
-        /// Args:
+        /// .. note::
-        ///     index: The position at which to insert the new frames.
+        ///    Inserting operations are expensive and should be used carefully.
-        ///     count: The number of frames to insert.
+        ///    Massively calling this function may result in bad performance.
-        ///     delta_time: The delta time value for the new frames.
         /// 
-        /// Raises:
+        /// :param index: The position at which to insert the new frames.
-        ///     RuntimeError: If the index is out of range.
+        /// :type index: int
+        /// :param count: The number of frames to insert.
+        /// :type count: int
+        /// :param delta_time: The delta time value for the new frames.
+        /// :type delta_time: float
+        /// :returns: None
+        /// :rtype: None
+        /// :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)?)
@@ -294,12 +331,17 @@ mod tasfile {
 
         /// Removes frames from the TAS file within the specified range (inclusive).
         /// 
-        /// Args:
+        /// .. note::
-        ///     index_from: The starting index (inclusive) of the range to remove.
+        ///    Removing operations are expensive and should be used carefully.
-        ///     index_to: The ending index (inclusive) of the range to remove.
+        ///    Massively calling this function may result in bad performance.
         /// 
-        /// Raises:
+        /// :param index_from: The starting index (inclusive) of the range to remove.
-        ///     RuntimeError: If either index is out of range or if index_to < index_from.
+        /// :type index_from: int
+        /// :param index_to: The ending index (inclusive) of the range to remove.
+        /// :type index_to: int
+        /// :returns: None
+        /// :rtype: None
+        /// :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)?)
         }
@@ -310,12 +352,12 @@ mod tasfile {
     #[pyfunction]
     /// Creates a new TAS file with a specified number of frames, all having the same delta time.
     /// 
-    /// Args:
+    /// :param count: The number of frames to create in the new TAS file.
-    ///     count: The number of frames to create in the new TAS file.
+    /// :type count: int
-    ///     delta_time: The delta time value for all frames in the new TAS file.
+    /// :param delta_time: The delta time value for all frames in the new TAS file.
-    /// 
+    /// :type delta_time: float
-    /// Returns:
+    /// :returns: A new TasFile instance with the specified number of frames.
-    ///     A new TasFile instance with the specified number of frames.
+    /// :rtype: TasFile
     fn create(count: usize, delta_time: f32) -> PyResult<TasFile> {
         Ok(TasFile { inner: RsTasFile::new(vec![RsTasFrame::with_delta_time(delta_time); count]) })
     }
@@ -323,14 +365,11 @@ mod tasfile {
     #[pyfunction]
     /// Loads a TAS file from disk.
     /// 
-    /// Args:
+    /// :param filename: The path to the TAS file to load.
-    ///     filename: The path to the TAS file to load.
+    /// :type filename: str
-    /// 
+    /// :returns: A TasFile instance loaded from the specified file.
-    /// Returns:
+    /// :rtype: TasFile
-    ///     A TasFile instance loaded from the specified file.
+    /// :raises RuntimeError: If the file cannot be loaded or is invalid.
-    /// 
-    /// Raises:
-    ///     RuntimeError: If the file cannot be loaded or is invalid.
     fn load(filename: &str) -> PyResult<TasFile> {
         Ok(TasFile { inner: RsTasFile::load(filename)? })
     }
@@ -338,12 +377,13 @@ mod tasfile {
     #[pyfunction]
     /// Saves a TAS file to disk.
     /// 
-    /// Args:
+    /// :param file: The TasFile instance to save.
-    ///     file: The TasFile instance to save.
+    /// :type file: TasFile
-    ///     filename: The path where the TAS file should be saved.
+    /// :param filename: The path where the TAS file should be saved.
-    /// 
+    /// :type filename: str
-    /// Raises:
+    /// :returns: None
-    ///     RuntimeError: If the file cannot be saved.
+    /// :rtype: None
+    /// :raises RuntimeError: If the file cannot be saved.
     fn save(file: &TasFile, filename: &str) -> PyResult<()> {
         Ok(file.inner.save(filename)?)
     }