docs for function parameters are mostly wrong

[rhaas80]

The docs use

    Returns:
        Mass (float): The Stars' masses
        Radius (float): The Stars's radius

which gets rendered as

that is the 2nd line gets interpreted as a return type.

[tuhinbits]

Thank you @rhaas80 for identifying these documentation issues. You've brought up an important point that we need to address.

Upon further review, we recognize that there are likely several documentation inconsistencies throughout the codebase similar to what you've identified. While the underlying code is in the production stage and functioning correctly for scientific calculations, we acknowledge that proper documentation is crucial for maintainability and new user onboarding.

Action Plan: We're committing to a comprehensive review of all function documentation by next week. This will include:

1. Verifying parameter descriptions match actual function signatures
2. Ensuring return value documentation accurately reflects actual return types
3. Correcting typos and improving clarity throughout
4. Adding examples where helpful for complex functions

Hopefully, the comprehensive documentation overhaul will be completed by next week (25th May 2025).

We greatly appreciate your careful review, as it has highlighted an area of our codebase that needs improvement. While the code is functionally sound and in production use by several research teams, clear and accurate documentation is essential for sustainable development. Your feedback is helping us make the codebase more accessible to the broader scientific community.

If you notice any other specific documentation issues in the meantime, please continue to let us know.