Improve comparison docs and re-export the array-comparing function

[HagaiHargil]

Closes #349.

This PR slightly improves the compute::comparison module:

1. It adds extensive top-level documentation with examples and doc-tests.
2. It adds or expands the documentation of the main comparison functions.
3. It re-exports the array-comparing functions in the statically-typed case.

One breaking change which I kept in a separate commit and I'm not quite sure about is to change the scalar-oriented comparison functions from using the _non_null variants to the standard variants, the ones which check whether the rhs is valid first. If this is unwanted for some reason I'll happily revert it back.

[codecov]

Codecov Report

Merging #404 (696403b) into main (06892e9) will increase coverage by 0.05%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #404      +/-   ##
==========================================
+ Coverage   80.91%   80.96%   +0.05%     
==========================================
  Files         347      347              
  Lines       22098    22141      +43     
==========================================
+ Hits        17880    17926      +46     
+ Misses       4218     4215       -3     

Impacted Files	Coverage Δ
src/compute/comparison/binary.rs	67.41% <ø> (ø)
src/compute/comparison/boolean.rs	70.10% <ø> (ø)
src/compute/comparison/mod.rs	92.16% <ø> (ø)
src/compute/comparison/primitive.rs	91.01% <ø> (ø)
src/compute/comparison/utf8.rs	67.41% <ø> (ø)
src/io/json_integration/write.rs	0.00% <0.00%> (-6.25%)	⬇️
tests/it/array/utf8/mod.rs	97.64% <0.00%> (-2.36%)	⬇️
tests/it/array/binary/mod.rs	98.57% <0.00%> (-1.43%)	⬇️
src/array/utf8/mod.rs	81.42% <0.00%> (ø)
src/array/fixed_size_binary/mod.rs	43.28% <0.00%> (+1.49%)	⬆️
... and 2 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 06892e9...696403b. Read the comment docs.

[jorgecarleitao]

Thank you very much for this, @HagaiHargil ! There are some tests failing before we can merge this.

[HagaiHargil]

Happy to help!

Sorry for not fixing the tests, I didn't have time to run the tests locally as I had to attend to other matters. I was also hoping to receive feedback from you regarding the change from the scalar_non_null type to the scalar type of functions. Do you think I should revert my change?

[jorgecarleitao]

The reason for _non_null is that I wanted to keep the _scalar reserved to be used by the scalar API, but either is fine. See how it feels best for you =)

[HagaiHargil]

Sorry for the delay, hope everything looks OK now.

[jorgecarleitao]

Beautifully written 🙇