Consolidate THRIFT.md into rustdoc comments

**Is your feature request related to a problem or challenge? Please describe what you are trying to do.**

- part of https://github.com/apache/arrow-rs/issues/5853

In the (epic!) PR that introduces the new thrift decoder from @etseidl
- https://github.com/apache/arrow-rs/pull/8530

The instructions and documentation for using the new thrift decoder are in a file called `THRIFT.md`

While the documentation is excellent, it has at least two challenges:
1. The doc examples are not tested regularly (and thus will likely slow bitrot / stop working)
2. It may be hard to find when looking through the code in the repo

**Describe the solution you'd like**
I would like the contents of THRIFT.md integrated into the codebase as doc comments

**Describe alternatives you've considered**

**Additional context**
There is some related discussion here
- https://github.com/apache/arrow-rs/pull/8476/files#r2388942168

Start by reading THRIFT.md and the new thrift decoder introduced in PR 8530, then review the related discussion in PR 8476. Identify where the decoder's public rustdoc comments belong, move the usage guidance and examples there, and verify that the examples are exercised as documentation tests.

Written by the indexing model from the issue text.