Guidelines for placing sync/async examples in docs vs standalone examples?

[vigneshsiva11]

Hi folks,

While working on parquet documentation, I noticed that
ArrowReaderBuilder provides both synchronous and asynchronous variants.

I was wondering if there are any preferred guidelines or conventions
for when examples should live directly in rustdoc comments
versus remaining as standalone examples under parquet/examples.

For example:

• Should async examples generally stay standalone?
• Or is the preference to move commonly used patterns into API docs
  for better discoverability?

I’d appreciate any guidance or pointers to existing conventions.

Thanks!

[Jefffrey]

It would be good if we can try push things into doctests for discoverability; the exception being if the example is too large then perhaps it would make more sense to live in examples as a distinct program.

[vigneshsiva11]

Thanks, that makes sense.

I’ll follow this guideline and prefer pushing smaller, commonly used
examples into doctests for discoverability, while keeping larger or more
complex examples as standalone programs.

This aligns well with the recent parquet documentation changes I worked on.
Appreciate the clarification!