[IMPROVEMENT] Pre-v0.2.0 Codebase Cleanup, API Standardization, and Documentation Pass

[shivasankarka]

What & Why

SciJo has accumulated a significant amount of functionality, but the codebase currently lacks consistent documentation and structural organization. This makes it difficult for both new contributors and maintainers to understand the APIs and internal design.

Before the v0.2.0 release, we should perform a focused cleanup to improve:

• Developer experience.
• API clarity and consistency and thus user experience.
• Maintainability of the codebase.

This issue tracks the cleanup PRs required to reach that state.

Proposed Solution

1. Standardize Docstrings
   Align all docstrings with the format used in Numojo and stamojo.
   Ensure each public function includes:

• Clear description
• Parameter definitions
• Return values
• Usage notes (where relevant) & Examples

2. Reorganize Utilities

• Move utility functions into appropriate utils modules under their corresponding functional domains.
• Avoid a monolithic or generic utilities module.
• Ensure utilities are colocated with the modules that primarily depend on them.

3. Clarify Function Signatures
   Many functions in SciJo currently mix compile-time parameters and runtime arguments in the inputs. This pattern should be documented and standardized.

Actions:

• Clearly document why certain inputs are compile-time parameters vs runtime arguments.
• Establish a consistent guideline for when each should be used.
• Refactor functions where the distinction is unclear or inconsistent.

Execution Plan

• Phase 1 — Structural Cleanup
  Reorganize the internal module structure to improve discoverability and maintainability.

  • Move utility functions into appropriate utils modules within their corresponding domains.
  • Split or rename modules where responsibilities are unclear or overloaded.
  • Remove unused or redundant helpers.
  • Ensure imports remain consistent after refactoring.

• Phase 2 — API Signature Review
  Standardize how functions handle inputs and clarify the distinction between compile-time parameters and runtime arguments.

  • Review existing functions for inconsistent parameter/argument usage.
  • Define and document guidelines for:
    • compile-time parameters
    • runtime arguments
  • Refactor function signatures where the distinction is unclear or inconsistent.
  • Update internal usages accordingly.

• Phase 3 — Docstrings Standardization
  Bring documentation across the codebase to a consistent standard.

  • Standardize docstrings using the format used in Numojo and stamojo.
  • Add missing docstrings for public APIs.
  • Ensure parameters, return values, and usage notes are clearly documented.
  • Update documentation to reflect any API changes from Phase 2.

• Phase 4 — Final Sweep
  Final cleanup before v0.2.0.

  • Address review feedback from previous phases.
  • Ensure linting and formatting are consistent.
  • Verify imports, typing, and docstring formatting.
  • Merge remaining cleanup PRs.