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?

Codecov Report

Base: 98.33% // Head: 98.33% // No change to project coverage 👍

Coverage data is based on head (754450c) compared to base (528e962).
Patch has no changes to coverable lines.

❗ Current head 754450c differs from pull request most recent head a5452e4. Consider uploading reports for the commit a5452e4 to get more accurate results

@@           Coverage Diff           @@
##             main    #1757   +/-   ##
=======================================
  Coverage   98.33%   98.33%           
=======================================
  Files          95       95           
  Lines        8343     8343           
=======================================
  Hits         8204     8204           
  Misses        139      139           

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

My motivation for doing this is related to #1270 and #1271, in particular since if we standardize the type lines then we can eventually do cool stuff like linking, etc.

It looks like there isn't a standard practice for multi-line type specifications: numpy/numpydoc#87

Oh, the LSST docstring guide has a section on docstring parameter types, with some examples pretty much from numpydoc. There are similarities and differences with matplotlib's conventions.

A lot of my motivation for this PR is that the numpydoc standard doesn't cover a bunch of edge cases that come up for packages that depend on NumPy pretty often, but seemingly don't come up for NumPy itself. I am trying to be consistent with primarily the matplotlib style guide and also the LSST standards.

The numpydoc standard would have been a much better place to clear up edge cases, but it seems pretty difficult to change since the PR I submitted on keyword-only and positional-only has been waiting on validation functionality to be added.

My main motivations for this PR are that standardizing the type specifications (ideally across projects) will:

• Make documentation easier to read because of improved consistency 😺 😺 😺 😺
• Make docstrings more concise and less DRY by using links to glossary terms for things like particle-like and array-like
• Set the stage for docstring autoformatters

@pheuer — might you be availble to review this? I was thinking you might have insight into parameter type description edge cases that are likely to come up in plasmapy.diagnostics, and possibly notice things that are missing. Thank you!

Having taken a look at your numpydoc PRs, the only worry I have is extending our docs too much beyond what the numpydoc standard currently offers. I don't want to break tooling that's based on a strict (as in, validated) interpretation of the standard.

Agreed. Going with matplotlib's style guide when possible partially addresses that worry, but not completely.

At the moment our docstrings go beyond what's in the numpydoc standard in a bunch of places. For example, a lot of what's in nitpick_ignore_regex is in there for the parameter type specifications for the nitpicky doc builds. Consistentifying docstring practices will mean we can simplify what's in nitpick_ignore_regex too.

I also wonder how this plays with xarray

Interesting! I looked at xarray's contributor guide and didn't see much about docstrings.

But that's also a worry for another day.

That is absolutely my favorite type of worry! 😹