Fix incorrect API usages in documentation code examples

- SpikeParser: replace nonexistent params (threshold_start, min_width) with valid ones (prominence, distance, width)
- _ignored: rewrite section to note it's private, recommend contextlib.suppress
- to_json: fix positional arg to keyword (filename=), add note that from_json is unimplemented
- IVCurveParser: change keyword arg to positional

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: a-fa

docs/_build/doc_example_fixes.md

@@ -0,0 +1,11 @@
+# Documentation Code Example Fixes
+
+Fixes for incorrect API usages found in documentation code examples.
+
+| File | Line | Before | After | Reason |
+|------|------|--------|-------|--------|
+| `docs/api/core.rst` | 199 | `SpikeParser(threshold_start=0.15, threshold_end=0.15, min_width=10, max_width=10000)` | `SpikeParser(prominence=0.15, distance=100, width=(10, 10000))` | Parameters `threshold_start`, `threshold_end`, `min_width`, `max_width` don't exist in SpikeParser. Actual params: `height`, `threshold`, `distance`, `prominence`, `width`, etc. |
+| `docs/api/core.rst` | 227 | `from ionique.core import ignored` | Replaced section: notes `_ignored` is internal, recommends `contextlib.suppress` | Function is `_ignored` (private). Not importable as `ignored`. Replaced with standard library equivalent. |
+| `docs/parsers_guide.rst` | 128 | `parser.to_json("my_parser.json")` | `parser.to_json(filename="my_parser.json")` | `to_json()` takes `filename` as keyword arg, not positional. |
+| `docs/parsers_guide.rst` | 132 | `restored = Parser.from_json(json_str)` | Removed; added note that `from_json` is not yet implemented | `from_json` returns `None` (stub). Showing it as working is misleading. |
+| `docs/parsers/other_parsers.rst` | 202 | `IVCurveParser(voltage=voltage_array)` | `IVCurveParser(voltage_array)` | `voltage` is a positional argument in the constructor. |

docs/api/core.rst

@@ -197,10 +197,9 @@ Use the ``parse()`` method to subdivide segments using parser objects:
 
    # Create a parser
    parser = SpikeParser(
-       threshold_start=0.15,
-       threshold_end=0.15,
-       min_width=10,
-       max_width=10000
+       prominence=0.15,
+       distance=100,
+       width=(10, 10000)
    )
 
    # Parse events within each voltage step
@@ -217,27 +216,24 @@ Use the ``parse()`` method to subdivide segments using parser objects:
 Utilities
 ---------
 
-ignored
-^^^^^^^
+_ignored (internal)
+^^^^^^^^^^^^^^^^^^^
 
-A context manager to suppress specific exceptions (replaces try/except/pass):
+``_ignored`` is a private context manager used internally to suppress specific
+exceptions. It is not part of the public API.
 
-.. code-block:: python
+For your own code, use the equivalent pattern from the standard library:
 
-   from ionique.core import ignored
+.. code-block:: python
 
-   # Instead of:
-   try:
-       value = some_dict["missing_key"]
-   except KeyError:
-       pass
+   from contextlib import suppress
 
-   # Use:
-   with ignored(KeyError):
+   # Suppress a specific exception
+   with suppress(KeyError):
        value = some_dict["missing_key"]
 
-   # Can ignore multiple exception types
-   with ignored(KeyError, AttributeError):
+   # Suppress multiple exception types
+   with suppress(KeyError, AttributeError):
        value = obj.missing_attr
 
 .. note::

docs/parsers/other_parsers.rst

@@ -199,7 +199,7 @@ relationships from multi-voltage-step recordings.
 
    from ionique.parsers import IVCurveParser
 
-   parser = IVCurveParser(voltage=voltage_array)
+   parser = IVCurveParser(voltage_array)
    patterns = parser.parse()
    # Returns matched voltage patterns for IV analysis
 

docs/parsers_guide.rst

@@ -124,12 +124,15 @@ Parsers support JSON serialization for reproducibility:
 
 .. code-block:: python
 
-   # Save configuration
-   json_str = parser.to_json("my_parser.json")
+   # Save configuration to file
+   parser.to_json(filename="my_parser.json")
 
-   # Reload
-   from ionique.parsers import Parser
-   restored = Parser.from_json(json_str)
+   # Get JSON string without saving to file
+   json_str = parser.to_json()
+
+.. note::
+   ``from_json`` is defined but not yet fully implemented. Parser
+   restoration from JSON will be available in a future release.
 
 .. toctree::
    :maxdepth: 1