DOC: clarify save_pairs_from_cube docstring

[rcomer]

🚀 Pull Request

Description

I'm glad this function exists publicly as it was the solution to my problem today but I found the docstring confusing: because it said it could convert an iterable of cubes, I tried passing a cubelist, which failed because cubelists have no shape attribute.

I also note that the target parameter does not appear to be used for anything, but I don't think I want to pull on that thread right now...

---

Consult Iris pull request check list

[rcomer]

Renders like this

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 89.74%. Comparing base (0ef0bc5) to head (5c5dc18).
Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5783   +/-   ##
=======================================
  Coverage   89.74%   89.74%           
=======================================
  Files          92       92           
  Lines       22941    22942    +1     
  Branches     5463     5464    +1     
=======================================
+ Hits        20589    20590    +1     
  Misses       1620     1620           
  Partials      732      732           

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

[pp-mo]

the target parameter does not appear to be used for anything

I chased this down. It used to have a role in "rules logging", which we got rid of a long time ago.

I'm also not sure how we go about tidying this.
Given how obscure this is, perhaps we could even just remove it (and the one in "as_fields"), and issue a warning in a whatsnew ?
I mean, maybe we don't need to be as seriously backwards-compatible as Iris.
@trexfeathers what do you reckon to this one ?

[pp-mo]

I'm glad this function exists publicly as it was the solution to my problem today
BTW maybe you can just as well use "as_fields" ? I'd be interested to know if not.

[rcomer]

BTW maybe you can just as well use "as_fields" ? I'd be interested to know if not.

Yes I could and I think that would be cleaner - thanks! I got here by looking at the example in the user guide which I think could also use as_fields.

[trexfeathers]

Given how obscure this is, perhaps we could even just remove it (and the one in "as_fields"), and issue a warning in a whatsnew ?

Yup, that's my preferred solution. We can always bugfix it back in if someone's calls are still expecting more arguments.

[pp-mo]

OK it's backwards-breaking, but we've discussed that enough I think.
Let's run with it + see what happens!

[rcomer]

Thanks @pp-mo!