docs: explain optional boolean args in from_native

[MarcoGorelli]

closes #1420

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

Related issues

• Related issue #<issue number>
• Closes #<issue number>

Checklist

• Code follows style guide (ruff)
• Tests added
• Documented the changes

If you have comments or can explain your changes, please do so below

[FBruzzesi]

Is there a reason to have Nones in the first place? From a user point of view, I think it would be more clear to have boolean defaults 🤔

[MarcoGorelli]

For some of these, yes - good call. That would still be backwards-compatible. For others (e.g. strict / pass_through) we explicitly check is None to ensure that users don't pass both together, so at least until stable.v2 I think they need to stay as bool | None

The other one which we can't change is allow_series, because we check for the invalid combination allow_series=False, series_only=True

Agree on simplifying where possible though, thanks 👍

[MarcoGorelli]

temporary (hopefully 🤞 ) workaround for mkdocstrings/mkdocstrings#716

[MarcoGorelli]

thanks for your review, and thanks @emilykl for helping us improve the docs, really appreciate this and the other suggestions you made!