(datafusion) 01/01: docs: note the rustdoc trick for hiding use statements in examples (#25718)

[gi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-25718-05d434f1fbc64b5792d80b83594bc799526542e0
in repository https://gitbox.apache.org/repos/asf/datafusion.git

commit fcab0020c173b48d870934f0884c1bb2d150d2a8
Author: Alessandro Solimando <as...@apache.org>
AuthorDate: Thu Sep 24 21:13:34 2026 +0000

    docs: note the rustdoc trick for hiding use statements in examples (#25718)
    
    ## Which issue does this PR close?
    
    None. This is a small, standalone documentation addition.
    
    ## Rationale for this change
    
    The "API Documentation Examples" section of the testing guide explains
    that doctests are
    checked by `cargo test --doc`, but says nothing about keeping them
    readable. @alamb pointed
    out on PR #25689 that prefixing a line with `#` keeps it compiled while
    hiding it from the
    rendered docs, most useful for `use` statements.
    
    ## What changes are included in this PR?
    
    Add a short note and example to
    `docs/source/contributor-guide/testing.md` documenting this.
    
    ## Are these changes tested?
    
    N/A, documentation only.
    
    ## Are there any user-facing changes?
    
    No, contributor documentation only.
    
    ----
    
    Disclaimer: I used AI to assist in the code generation, I have manually
    reviewed the output and it matches my intention and understanding.
---
 docs/source/contributor-guide/testing.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/source/contributor-guide/testing.md b/docs/source/contributor-guide/testing.md
index 4ba7d9d011..4c097ae498 100644
--- a/docs/source/contributor-guide/testing.md
+++ b/docs/source/contributor-guide/testing.md
@@ -176,6 +176,20 @@ cargo test --doc
 As with other Rust projects, examples in doc comments in `.rs` files are
 automatically checked to ensure they work and evolve along with the code.
 
+Prefix a line with `# ` (a `#` followed by a space) to keep it compiled and
+run, but hidden from the rendered documentation. This is most useful for
+`use` statements, since readers care about the API being demonstrated, not
+its import boilerplate:
+
+````rust
+/// ```
+/// # use std::sync::Arc;
+/// let value = Arc::new(42);
+/// ```
+````
+
+Only the `let value = ...` line renders.
+
 ### User Guide Documentation
 
 Rust example code from the user guide (anything marked with \`\`\`rust) is also


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org