Visitar URL original
Improve consistency of docstrings, annotations, and signatures in `plasmapy.particles` by namurphy · Pull Request #1718 · PlasmaPy/PlasmaPy · GitHub
Skip to content

Improve consistency of docstrings, annotations, and signatures in plasmapy.particles - #1718

Merged
StanczakDominik merged 41 commits into
PlasmaPy:mainfrom
namurphy:atomic-docstrings
Sep 17, 2022
Merged

Improve consistency of docstrings, annotations, and signatures in plasmapy.particles#1718
StanczakDominik merged 41 commits into
PlasmaPy:mainfrom
namurphy:atomic-docstrings

Conversation

@namurphy

@namurphy namurphy commented Aug 31, 2022 •
edited
Loading

Copy link
Copy Markdown
Member

This PR is an effort to make the user experience for plasmapy.particles more consistent and in-line with our more recent practices.

  • Introduce the term "atom-like"
  • Apply particle-like and atom-like to type lines in parameters sections of docstrings
  • Make Z and mass_numb keyword-only in ionic_symbol and particle_symbol
  • Apply consistent descriptions for Z and mass_numb
  • Remove the names of the variables that get returned (since they're usually quite redundant with the function name)
  • Update annotations from eons past when it was recommended that we didn't use typing.Optional when the default argument is None
  • Change `int` to integer in type lines (since a dimensionless Quantity can be used too)
  • Apply some reST formatting or substitutions
  • Specify defaults in a way that is consistent with the numpydoc standard
  • Apply ParticleLike as annotations; this may overlap with Refactor @particle_input and broaden allowed function annotations #1057
  • Apply more consistent formatting of docstrings
  • Used -> typing.NoReturn instead of -> typing.None for return annotations
  • Make docstring formatting a little more consistent
  • Remove TypeError from "Raises" sections following recent updates to doc guide in Update guidelines for "Parameters", "Raises", and "Warns" sections of docstrings #1667

@github-actions github-actions Bot added the plasmapy.particles Related to the plasmapy.particles subpackage label Aug 31, 2022
@codecov

codecov Bot commented Aug 31, 2022 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

Base: 98.13% // Head: 98.13% // Increases project coverage by +0.00% 🎉

Coverage data is based on head (213e9e8) compared to base (f0d1698).
Patch coverage: 100.00% of modified lines in pull request are covered.

Additional details and impacted files 
@@           Coverage Diff           @@
##             main    #1718   +/-   ##
=======================================
  Coverage   98.13%   98.13%           
=======================================
  Files          87       87           
  Lines        8134     8135    +1     
=======================================
+ Hits         7982     7983    +1     
  Misses        152      152
Impacted Files Coverage Δ
plasmapy/particles/_factory.py 100.00% <ø> (ø)
plasmapy/particles/symbols.py 100.00% <ø> (ø)
plasmapy/particles/_parsing.py 98.44% <100.00%> (ø)
plasmapy/particles/atomic.py 100.00% <100.00%> (ø)
plasmapy/particles/ionization_state.py 94.92% <100.00%> (ø)
plasmapy/particles/ionization_state_collection.py 91.90% <100.00%> (ø)
plasmapy/particles/nuclear.py 96.55% <100.00%> (+0.04%) ⬆️
plasmapy/particles/particle_class.py 98.99% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

@github-actions github-actions Bot added the docs PlasmaPy Docs at http://docs.plasmapy.org label Aug 31, 2022
namurphy added 24 commits August 31, 2022 14:49
@namurphy
Add changelog entry
5f64318
@namurphy
Update docstrings
4a783c3
@namurphy
Merge branch 'main' of github.com:PlasmaPy/PlasmaPy into atomic-docst…
823f0af 
…rings
@namurphy
Update docstrings in atomic.py
5706889
@namurphy
Update docstrings in ionization_state.py
4583150
@namurphy
Update docstrings in ionization_state_collection.py
f94ee2b
@namurphy
Update docstrings & annotations in nuclear.py
d8ff986
@namurphy
Update docstrings & annotations in particle_class.py
9e740cc
@namurphy
Update docstrings & annotations in particle_collections.py
e86636e
@namurphy
Update changelog entry
425021b
@namurphy
Update docstrings & annotations in atomic.py
6dc7ade
@namurphy
Update docstrings & annotations in ionization_state_collection.py
6aeaa5f
@namurphy
Update docstrings & annotations in nuclear.py
77982eb
@namurphy
Update docstrings & annotations in symbols.py
2ba83a4
@namurphy
Update docstrings & annotations in atomic.py
aa162e5
@namurphy
Update docstrings & annotations in atomic.py
5f21a1f
@namurphy
Update docstrings & annotations in _factory.py
790d081
@namurphy
Update docstrings & annotations in _parsing.py
905e431
@namurphy
Correct reST substitution
1b38678
@namurphy
Update docstrings & annotations for atomic.py
78b4cfc
@namurphy
Update docstrings & annotations for particle_class.py
fa55471
@namurphy
Update docstrings & annotations for symbols.py
2d4ebf9
@namurphy
Update docstrings & annotations for symbols.py
27a367b
@namurphy
Update docstrings & annotations for atomic.py
2d2007a
@namurphy namurphy changed the title Update docstrings in plasmapy.particles Improve consistency of docstrings, annotations, and signatures in plasmapy.particles Sep 1, 2022
This was referenced Sep 2, 2022
Closed
Merged
@namurphy
namurphy requested a review from a team as a code owner September 14, 2022 18:00
@namurphy
namurphy requested review from StanczakDominik and removed request for a team September 14, 2022 18:00
@github-actions

github-actions Bot commented Sep 14, 2022

Copy link
Copy Markdown

Thank you for contributing to PlasmaPy! The project's future depends deeply on contributors like you, so we deeply appreciate it! 🌱 The following checklist will be used by the code reviewer to help guide the code review process.

  • Overall
    • Does the PR do what it intends to do?
    • Except for very minor changes, is a changelog entry included and consistent with the changelog guide?
    • Are the continuous integration checks passing? (Most linter problems can be automagically fixed by commenting on this PR with pre-commit.ci autofix.)
  • Code
    • Is new/updated code understandable and consistent with the coding guide?
    • Are there ways to greatly simplify the implementation?
    • Are there any large functions that should be split up into shorter functions?
  • Tests
    • Are tests added/updated as required, and consistent with the testing guide?
    • Are the tests understandable?
    • Do the tests cover all important cases?
  • Docs
    • Are docs added/updated as required, and consistent with the doc guide?
    • Are the docs understandable?
    • Do the docs show up correctly in the preview, including Jupyter notebooks?

@namurphy
Reduce redundancy in common_links.rst
90f5364
@namurphy
charge -> electrical charge
c68fda7 
To be a little more explicit about the physical type
StanczakDominik
StanczakDominik reviewed Sep 15, 2022
View reviewed changes

@StanczakDominik StanczakDominik left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Partial review for now, because I managed to trick myself into wanting to eat breakfast earlier.

  • atomic
  • nuclear
  • particle_class
  • symbols

Comment thread changelog/1718.breaking.rst Resolved
Comment thread docs/glossary.rst Outdated
Comment on lines +25 to +32
atom-like
A |particle-like| `object` is **atom-like** if it is or could be
cast into:

* A |Particle| representing an element, isotope, or ion; or
* A |ParticleList| including only elements, isotopes, or ions.

For full details, please refer to |particle-like|.

@StanczakDominik StanczakDominik Sep 15, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When is a particle not atom-like?

Comment thread plasmapy/particles/ionization_state.py Resolved
Comment thread plasmapy/particles/ionization_state.py Resolved
@StanczakDominik
StanczakDominik self-requested a review September 15, 2022 04:27
StanczakDominik
StanczakDominik reviewed Sep 16, 2022
View reviewed changes
Comment thread docs/glossary.rst Resolved
StanczakDominik
StanczakDominik approved these changes Sep 16, 2022
View reviewed changes

@StanczakDominik StanczakDominik left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good all in all, except that AtomLike term is still a tad vague to me.

@namurphy

namurphy commented Sep 16, 2022

Copy link
Copy Markdown
Member Author

I just updated the description for atom-like with some examples. For information on what constitutes a valid representation of a particle, I wanted to make sure to refer users to the definition of particle-like so that we don't end up repeating the same information in multiple places.

@StanczakDominik

StanczakDominik commented Sep 16, 2022

Copy link
Copy Markdown
Member

Okay, one last follow-up question. Is a single He-4, not in a list with an electron, atom-like?

@StanczakDominik

StanczakDominik commented Sep 17, 2022

Copy link
Copy Markdown
Member

All right, let's get it in! Sorry for the, er, iterative approach in this review 😅

@StanczakDominik
StanczakDominik merged commit 7477ce2 into PlasmaPy:main Sep 17, 2022
@namurphy
namurphy deleted the atomic-docstrings branch September 17, 2022 13:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanczakDominik StanczakDominik StanczakDominik approved these changes

Assignees

No one assigned

Labels

docs PlasmaPy Docs at http://docs.plasmapy.org plasmapy.particles Related to the plasmapy.particles subpackage

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@namurphy @StanczakDominik