Consolidate THRIFT.md into rustdoc comments

[alamb]

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

• part of [EPIC] A collection of items to improve speed of parquet metadata encoding #5853

In the (epic!) PR that introduces the new thrift decoder from @etseidl

• Use custom thrift parser for parquet metadata (phase 1 of Thrift remodel) #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

[etseidl]

I've hit my first roadblock while trying to pull THRIFT.md into parquet/src/file/metadata/thrift/mod.rs. The thrift decoding code has been kept private, but doctest can only use public APIs.

The only workaround is to ignore all the code blocks, but then that defeats the purpose of point 1. The markdown is rendered properly, so point 2 is at least addressed.