In my opinion, examples that only use the parquet library code / show how to use its API are best left in the API docs for discoverability
Examples are useful when showing how to interact with other libraries / systems that can't be run in the context of the the API dos -- for example[1] which shows how to read Arrow arrays using zero copy and requires using a library (mmap) that is not a dependency of the arrow library Andrew [1]: https://github.com/apache/arrow-rs/blob/main/arrow/examples/zero_copy_ipc.rs On Wed, Jan 14, 2026 at 7:08 AM Vignesh Siva <[email protected]> wrote: > Hi all, > > I’m contributing to arrow-rs and recently worked on consolidating a parquet > example into the ArrowReaderBuilder documentation. > > While doing so, I noticed that there are both synchronous and asynchronous > reader APIs available. I wanted to ask if there are any preferred > guidelines > or conventions for when examples should live directly in rustdoc comments > versus remaining as standalone examples (for example under > parquet/examples). > > In particular: > - Is there a general preference to keep async examples as standalone? > - Or should commonly used patterns (sync or async) be documented directly > in API docs for better discoverability? > > Any guidance or pointers to existing conventions would be appreciated. > > Thanks, > Vignesh >
