ARROW-15431: [Python] Address docstrings in Schema

[AlenkaF]

This PR is adding docstring examples to:

• pyarrow.Schema class methods and attributes.

[github-actions]

https://issues.apache.org/jira/browse/ARROW-15431

[jorisvandenbossche]

Looks great! A few small points of feedback

[jorisvandenbossche]

Linting is also failing with

 pyarrow.lib.Schema.to_string
-> pyarrow.lib.Schema.to_string(self, truncate_metadata=True, show_field_metadata=True, show_schema_metadata=True)
PR01: Parameters {'show_field_metadata', 'show_schema_metadata'} not documented

pyarrow.lib.Schema.add_metadata
-> pyarrow.lib.Schema.add_metadata(self, metadata)
PR01: Parameters {'metadata'} not documented

Not fully sure why that is happening, though (since you didn't change the Parameter sections, and those actually seem to be documented)

[AlenkaF]

This linting error is really strange and also happening on another PR. Will look at it in more detail later today or tomorrow.

[wjones127]

I love the example data 🦩

Left a few minor suggestions.

[ursabot]

Benchmark runs are scheduled for baseline = dd42155 and contender = 76d064c. 76d064c is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished ⬇️0.0% ⬆️0.0%] ec2-t3-xlarge-us-east-2
[Finished ⬇️0.54% ⬆️0.04%] test-mac-arm
[Failed ⬇️0.71% ⬆️0.0%] ursa-i9-9960x
[Finished ⬇️0.09% ⬆️0.0%] ursa-thinkcentre-m75q
Buildkite builds:
[Finished] <https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/467| 76d064c7 ec2-t3-xlarge-us-east-2>
[Finished] <https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/452| 76d064c7 test-mac-arm>
[Failed] <https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/453| 76d064c7 ursa-i9-9960x>
[Finished] <https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/462| 76d064c7 ursa-thinkcentre-m75q>
[Finished] <https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/466| dd421557 ec2-t3-xlarge-us-east-2>
[Finished] <https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/451| dd421557 test-mac-arm>
[Finished] <https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/452| dd421557 ursa-i9-9960x>
[Finished] <https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/461| dd421557 ursa-thinkcentre-m75q>
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python, R. Runs only benchmarks with cloud = True
test-mac-arm: Supported benchmark langs: C++, Python, R
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java