add comments

Author: x0rw

exts/rust-code-runner/__init__.py

@@ -3,14 +3,13 @@
 from . import rustc 
 import os
 def setup(app):
-
     app.output_rust_file = "exts/rust-code-runner/generated.rs"
     if os.path.isfile(app.output_rust_file):
         with open(app.output_rust_file, 'w'):
             pass  
 
     # we hook into 'source-read' because data is mutable at this point and easier to parse 
-    # and it also makes  this extension indepandant from `needs`
+    # and it also makes this extension indepandant from `needs`.
     #
     app.connect('source-read', rust_examples_aggregate.preprocess_rst_for_rust_code)
     app.connect('build-finished', rustc.check_rust_test_errors)

exts/rust-code-runner/generated.rs

@@ -1,3 +1,43 @@
+// ==== Code Block 1 ====
+#[test]
+fn test_block_coding_guidelines_concurrency_1() {
+            test ga
+}
+
+// ==== Code Block 2 ====
+#[test]
+fn test_block_coding_guidelines_concurrency_2() {
+            test ga
+}
+
+// ==== Code Block 3 ====
+#[test]
+fn test_block_coding_guidelines_concurrency_3() {
+       .. compliant_example::
+          :id: compl_ex_yp7aQuEi3Sag 
+          :status: draft
+}
+
+// ==== Code Block 4 ====
+#[test]
+fn test_block_coding_guidelines_concurrency_4() {
+            test ga
+}
+
+// ==== Code Block 5 ====
+#[test]
+fn test_block_coding_guidelines_concurrency_5() {
+       .. compliant_example::
+          :id: compl_ex_gqeLAg0YBu9P 
+          :status: draft
+}
+
+// ==== Code Block 6 ====
+#[test]
+fn test_block_coding_guidelines_concurrency_6() {
+            test ga
+}
+
 // ==== Code Block 1 ====
 #[test]
 fn test_block_coding_guidelines_expressions_1() {

exts/rust-code-runner/rustc.py

@@ -1,6 +1,22 @@
 import json
+import subprocess
 
 def print_code_snippet(file_path, line_num, context=3):
+    """
+    Prints a code snippet from a file with context around a specific line.
+
+    This function is typically used to display source code around an error line
+    for better debugging and error reporting.
+
+    Args:
+        file_path (str): Path to the source file.
+        line_num (int): The line number where the error occurred (1-based index).
+        context (int, optional): The number of lines to display before and after
+            the error line. Defaults to 3.
+
+    Returns:
+        None
+    """
     try:
         stripped_lines = []
         with open(file_path, "r") as f:
@@ -14,7 +30,21 @@ def print_code_snippet(file_path, line_num, context=3):
     except Exception as e:
         print(f"Could not read file {file_path}: {e}")
 
+    
 def parse_rustc_json(stderr: str, file):
+    """
+    Parses the JSON diagnostics output from `rustc`.
+
+    This function takes the standard error output (in JSON format) from the Rust compiler (`rustc`)
+    and processes it, possibly filtering or reporting diagnostics relevant to the specified file.
+
+    Args:
+        stderr (str): The JSON-formatted stderr output from `rustc`.
+        file: The file object or path that the diagnostics should relate to.
+
+    Returns:
+        Any
+    """
     for line in stderr.splitlines():
         line = line.strip()
         if not line:
@@ -46,14 +76,30 @@ def parse_rustc_json(stderr: str, file):
         else:
             print(f"{level}: {msg}")
 
-import subprocess
+
 def check_rust_test_errors(app, exception):
+   """
+    Sphinx 'build-finished' event handler that compiles the generated Rust file in test mode.
+
+    This function is connected to the Sphinx build lifecycle and is executed after the build finishes.
+    It invokes `rustc` in test mode on the generated Rust file and reports any compilation or test-related
+    errors.
+
+    Args:
+        app: The Sphinx application object. Must have an `output_rust_file` attribute containing
+             the path to the generated Rust source file.
+        exception: Exception raised during the build process, or None if the build completed successfully.
+
+    """
     rs_path = app.output_rust_file
+    # Run the Rust compiler in test mode with JSON error output format.
+    # capturing stdout and stderr as text.
     result = subprocess.run(
-        ["rustc", "--test", "--edition=2021", "--error-format=json", rs_path],
+        ["rustc", "--test", "--edition=2024", "--error-format=json", rs_path],
         capture_output=True,
         text=True
     )
+
     if result.returncode != 0:
         print("--- rustc Errors/Warnings ---")
         parse_rustc_json(result.stderr, app.output_rust_file)