Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Move documentation for charge/mass number parameters to Other Parameters section in docstrings #2218

Open
namurphy opened this issue Jun 22, 2023 · 4 comments
Open

Move documentation for charge/mass number parameters to Other Parameters section in docstrings #2218

namurphy opened this issue Jun 22, 2023 · 4 comments
Labels
docs PlasmaPy Docs at http://docs.plasmapy.org Plasma Lv0 | Novice Issues that do not require knowledge of physics plasmapy.particles Related to the plasmapy.particles subpackage Python Lv0 | Novice Issues that require little to no knowledge of Python

Comments

@namurphy
Copy link
Member

namurphy commented Jun 22, 2023 •
edited
Loading

Functions decorated by @particle_input can accept parameters for the mass number (mass_numb) and charge number (Z). These are not the primary parameters for functions, so it would probably be best to move these to the Other Parameters section of docstrings.

The sections should have the same order of sections as listed in the numpydoc standard. Most of the time the Other Parameters section should be just after the Returns section.

We should address this at the same time as #2024.
@namurphy namurphy added plasmapy.particles Related to the plasmapy.particles subpackage docs PlasmaPy Docs at http://docs.plasmapy.org Python Lv0 | Novice Issues that require little to no knowledge of Python Plasma Lv0 | Novice Issues that do not require knowledge of physics labels Jun 22, 2023
@namurphy
Copy link
Member Author

namurphy commented Jun 22, 2023 •
edited
Loading

Some related thoughts, not directly part of this issue.

  • I've also been wondering if it would be worth creating a decorator to add these to docstrings.
  • An alternative would be to make @particle_input do this automatically. This may violate the single responsibility principle, but would make it easier for these docstrings to be added consistently.
  • If we don't add a decorator, we might want to add a linter check to make sure that the charge number and mass number docstrings are consistent with the standardized form...though this might be a lot of work (unless we ask ChatGPT?) and there may be situations where we need specialized descriptions for particular functions.

@Spedi
Copy link
Contributor

Spedi commented Mar 27, 2024

Hi there!
I'm a freshman Applied Math student who's currently learning Python, and I'm trying to find easy issues to tackle in order to start contributing to Open Source projects.
Is there any chance that I can help you with this issue?

@namurphy
Copy link
Member Author

namurphy commented Mar 31, 2024 •
edited
Loading

Please feel free to go for it! It'd probably be best to start with the docstrings for plasmapy.particles.atomic and plasmapy.particles.symbols. Thank you!

@Spedi
Copy link
Contributor

Spedi commented Apr 2, 2024

Perfect, I made a PR for those two files.
I saw that in some files Z (charge number) has a real value and in others it has an integer value, should I always maintain the original value of it when I put it on Other Parameters?
Should I change all the others files that have functions decorated by @particle_input?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs PlasmaPy Docs at http://docs.plasmapy.org Plasma Lv0 | Novice Issues that do not require knowledge of physics plasmapy.particles Related to the plasmapy.particles subpackage Python Lv0 | Novice Issues that require little to no knowledge of Python
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@namurphy @Spedi