Enhance docstrings with detailed explanations and examples

[diegoabt]

While the current codebase includes docstrings for most functions, there is room for improvement in terms of clarity, detail, and usefulness. Comprehensive documentation makes the code easier to understand, use, and maintain. This is probably too general, so it might make sense to create a few sub-issues.