DOC: Revision of docstrings in the iterators' module

[jhlegarreta]

• ENH: Add None to b-vals iterators size parameter annotations
• ENH: Make linear_iterator return an iterator
• ENH: Remove unused parameter form bvalue_iterator prototype

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 68.24%. Comparing base (d9b390b) to head (8ceaf57).
Report is 12 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #29      +/-   ##
==========================================
+ Coverage   68.10%   68.24%   +0.13%     
==========================================
  Files          20       20              
  Lines         994      995       +1     
  Branches      130      130              
==========================================
+ Hits          677      679       +2     
  Misses        263      263              
+ Partials       54       53       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jhlegarreta]

Note especially this change:
https://github.com/nipreps/nifreeze/pull/29/files#diff-caf7665e7d0c7d0454e8984b460aa419f31154c8746083014c1524d306ab3644R110

X-referencing
nipreps/eddymotion#150 (comment)
nipreps/eddymotion#150 (comment)

[oesteban]

There seems to be some conflicts after the style update I made.

[oesteban]

I don't see why the iter() decoration to range, other than that looks good!

[jhlegarreta]

There seems to be some conflicts after the style update I made.

Force pushed; conflicts gone.

[oesteban]

In 6398249, I have added the following changes:

• Revert the removal of optional keyword arguments from docstrings. The rationale is that, if they are not documented there, the type hints in the signature are insufficient to introspect what keyword arguments may be provided and their behavior. As discussed above, you can use Other parameters for this as per numpydoc. However, in this particular case I find it overly verbose. Instead, I propose we explicitly label these arguments as optional, keyword argument.
• Rewrite the Returns section with Yields, following numpydocs' documentation, as all these are meant to yield values rather than return values.

In addition to those changes, I also rolled back the iter() decoration of the linear iterator, and replace it with an actual generator, for consistency with the other iterators.

You can always convert these generators to iterators or lists at any moment.

@jhlegarreta @effigies let me know if the above sounds reasonable.

[jhlegarreta]

In 6398249, I have added the following changes:

• Revert the removal of optional keyword arguments from docstrings. The rationale is that, if they are not documented there, the type hints in the signature are insufficient to introspect what keyword arguments may be provided and their behavior. As discussed above, you can use Other parameters for this as per numpydoc. However, in this particular case I find it overly verbose. Instead, I propose we explicitly label these arguments as optional, keyword argument.

Agreed that documenting these is useful in this case. Left a few style comment to make documenting these nicer/more Pythonin/Sphinxier if there is a way.

• Rewrite the Returns section with Yields, following numpydocs' documentation, as all these are meant to yield values rather than return values.

👍 Yield looks the right thing.

In addition to those changes, I also rolled back the iter() decoration of the linear iterator, and replace it with an actual generator, for consistency with the other > iterators.

OK.

@jhlegarreta @effigies let me know if the above sounds reasonable.

Changes look OK. The only inconsistency is the _iterator naming vs. them being generators.

[oesteban]

The only inconsistency is the _iterator naming vs. them being generators.

Let's then punt this inconsistency for the future, as the module is also called "iterators". They are indeed iterators (that's why the recommendation for the type hint of the return is Iterator), however they are not implemented exactly like proper Python iterators.

If the naming is too irritating for you or anyone, happy to see a future PR addressing this.