docs(python): Add deprecated LazyFrame.fetch back to API reference

[henryharbeck]

LazyFrame.fetch was deprecated, but not removed. It should still be discoverable in the docs until it is removed.
I also made two small drive-by changes to the docstring.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.70%. Comparing base (8bad2fd) to head (eff954f).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #17642      +/-   ##
==========================================
+ Coverage   80.69%   80.70%   +0.01%     
==========================================
  Files        1485     1485              
  Lines      195485   195485              
  Branches     2782     2782              
==========================================
+ Hits       157747   157772      +25     
+ Misses      37226    37201      -25     
  Partials      512      512              

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

[ritchie46]

I don't think we should do that. We discourage you to use it, so also don't clutter our reference guide with it.

[henryharbeck]

Hmm, but given that it is recently deprecated, there would like still be users with it in their code.
Should it be discoverable in the docs for those users after they see the deprecation warning from their code?

Everything else that is deprecated, but not yet removed is still in the API reference.

I guess to counter that - it was already recommended against using it before it was deprecated.
I was adding it back to the docs for consistency - but of course you make the call.

Please close if you still think there is no need to add it back.

[ritchie46]

Ok.. I need to ping @stinodego here on our policy.

[stinodego]

The policy is to keep the API reference entry for deprecated functionality until it is completely removed.

However, in this case, since it was only intended for debugging anyway, we decided to just remove it.

[henryharbeck]

Okay cool - makes sense.
Thank you and apologies for the extra work caused 😅