⚡ [Docs]: Enhance and Standardize Docstrings for the DSC Module

[PPeitsch]

Issue Type

Unclear documentation

Documentation Location

The entire pkynetics/technique_analysis/dsc/ module, including all sub-modules (baseline.py, peak_analysis.py, heat_capacity.py, etc.).

Current Documentation

Following recent refactoring, many docstrings within the new technique_analysis.dsc module are either incomplete, overly brief, or stylistically inconsistent. They often lack detailed descriptions of parameters (including units), return values, and potential exceptions. This makes it difficult for users to correctly and confidently use the module's functionality.

Suggested Changes

A comprehensive overhaul of all public-facing classes, methods, and functions within the pkynetics.technique_analysis.dsc module is required to ensure they strictly adhere to the NumPy docstring standard.

A complete docstring should include all relevant sections:

1. Summary: A concise one-line summary followed by a more detailed extended summary.
2. Parameters: A detailed list of all parameters, including:
   • name : type
   • A clear description of what the parameter does, its units (e.g., K, J/g, K/min), and its valid range or expected values.
3. Returns: A description of the returned object(s), including type and meaning of each element.
4. Raises: A list of exceptions that the function can raise and the conditions under which they occur.
5. See Also (Optional): References to other related functions or methods in the library.
6. Notes (Optional): Details about the implementation, algorithm, or scientific assumptions.
7. References (Optional): Citations to scientific papers or standards on which the method is based.
8. Examples: A short, runnable code snippet demonstrating the function's usage.

This effort will create a consistent, professional, and scientifically rigorous API documentation directly within the codebase.

Additional Context

This is a critical step for improving the overall quality of the library. High-quality docstrings directly translate into high-quality generated documentation on sites like Read the Docs and provide invaluable inline help in IDEs. This makes the library more accessible and trustworthy for the scientific community.

The implementation plan should include:

1. Systematic Review: Go through every file in the pkynetics.technique_analysis.dsc module.
2. Update Docstrings: For each public class, method, and function, rewrite the docstring to conform to the full NumPy standard.
3. Linter Integration: Introduce pydocstyle into the development dependencies and CI pipeline, configured to enforce the numpy convention.
4. Documentation Build: After updating, rebuild the Sphinx documentation locally to ensure all pages render correctly.

Guidelines

• I agree to follow this project's Contributing Guidelines
• I have checked that this issue hasn't been reported before