Minor: improve ParquetOpener docs

[alamb]

Which issue does this PR close?

Part of #4028

Rationale for this change

While working with @itsjunetime on #12135 we spent a while reviewing the code in ParquetOpener and I realized that the documentation could be improved

What changes are included in this PR?

Improve the documentation

Are these changes tested?

By CI

Are there any user-facing changes?

No functional changes, just docs

[alamb]

This in particular was unclear when @itsjunetime and I read the code (were the indexes in terms of file_schema or table_schema?) and was the impetus for this PR

[appletreeisyellow]

Thank you @alamb! The descriptions are helpful, especially those for bool values!

[comphead]

Nice, WDYT about enabling the missing_docs lint so every pub will force forced to be documented ?

[comphead]

https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=e486601506c2493123d2b4d9cca24727
here is the link to playground, the lint will require crate documentation and public entities

[alamb]

Nice, WDYT about enabling the missing_docs lint so every pub will force forced to be documented ?

I personally think it is a good idea, though I predict that if we do that we'll still end up with functions that are like "ParquetOpener: opens parquet" any other similar documentation that isn't particularly helpful.

But it might encourage enough that is better than no documentation 👍

[alamb]

Thanks for the review @appletreeisyellow and @comphead

[comphead]

I personally think it is a good idea, though I predict that if we do that we'll still end up with functions that are like "ParquetOpener: opens parquet" any other similar documentation that isn't particularly helpful.

But it might encourage enough that is better than no documentation 👍

I'll try to play on some small crate first, enabling the documentation and putting #[allow(missing_docs)] whenever it complains, so later it would be easier to find all undocumented methods and make contributions