Add type stubs and improve C code comments

Co-authored-by: gerlero <[email protected]>

Author: Copilot

src/foamlib/_c/_skip.pyi

@@ -0,0 +1,29 @@
+"""Type stubs for the _skip C extension module."""
+
+def skip(
+    contents: bytes | bytearray,
+    pos: int,
+    *,
+    newline_ok: bool = True,
+) -> int:
+    """
+    Skip whitespace and comments in OpenFOAM file content.
+    
+    This function skips over whitespace characters (space, tab, newline, etc.) and
+    both types of comments:
+    - Line comments starting with // (until the end of the line)
+    - Block comments enclosed in /* */
+    
+    Args:
+        contents: The byte content to parse (bytes or bytearray).
+        pos: The starting position in the content.
+        newline_ok: Whether newlines should be considered whitespace (default: True).
+                   When False, the function will stop at newline characters.
+    
+    Returns:
+        The new position after skipping whitespace and comments.
+    
+    Raises:
+        FoamFileDecodeError: If an unclosed block comment is encountered.
+    """
+    ...

src/foamlib/_c/skip.c

@@ -95,10 +95,10 @@ skip(PyObject *self, PyObject *args, PyObject *kwargs)
             continue;
         }
 
-        /* Handle block comments (slash-star ... star-slash) */
+        /* Handle block comments */
         if (next1 == '/' && next2 == '*') {
             pos += 2;
-            /* Find closing star-slash */ 
+            /* Find closing */ 
             int found = 0;
             while (pos + 1 < len) {
                 if (contents[pos] == '*' && contents[pos + 1] == '/') {
@@ -124,7 +124,7 @@ skip(PyObject *self, PyObject *args, PyObject *kwargs)
                     return NULL;
                 }
 
-                /* Create exception with keyword argument: FoamFileDecodeError(contents, len, expected="star-slash") */
+                /* Create exception with keyword argument */
                 PyObject *kwargs_exc = Py_BuildValue("{s:s}", "expected", "*/");
                 PyObject *args_exc = Py_BuildValue("(On)", contents_obj, len);