# Can the standard library please ban \`println!\` and similar functions from doctests? **URL:** \ **Category:** libs\ **Created:** [March 18, 2023, 7:18am UTC](https://internals.rust-lang.org/t/can-the-standard-library-please-ban-println-and-similar-functions-from-doctests/18534 "2023-03-18T07:18:30Z")\ **Posts on this page:** 6\ **Page:** 2
**Author:** ![the8472](https://avatars.discourse-cdn.com/v4/letter/t/0ea827/32.png) [@the8472](https://internals.rust-lang.org/u/the8472)\ **Post date:** [March 20, 2023, 2:06pm UTC](https://internals.rust-lang.org/t/can-the-standard-library-please-ban-println-and-similar-functions-from-doctests/18534/21 "2023-03-20T14:06:00Z")
Sometimes APIs make weak/fuzzy/subject-to-change promises in the prose, e.g. `Debug` impls. Using `println!` in the examples matches such prose because you'll get _some_ output while leaving the exact contents unspecified. And sometimes it's the order in which things happen that's relevant, e.g. when talking about threads or destructors. That is more easily demonstrated with `println!`. Writing those as asserting tests [is far more gnarly](https://github.com/rust-lang/rust/blob/356c651e6d013fe9ca1d47da278ba208a95dbcf9/library/alloc/tests/vec.rs#L1195-L1217). ---
**Author:** ![euclio](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/euclio/32/4705_2.png) [@euclio](https://internals.rust-lang.org/u/euclio)\ **Post date:** [March 20, 2023, 5:34pm UTC](https://internals.rust-lang.org/t/can-the-standard-library-please-ban-println-and-similar-functions-from-doctests/18534/22 "2023-03-20T17:34:19Z")
I like this. Rustdoc could also add the captured output to the rendered code block, similarly to how it displays a tooltip for examples marked `should_panic`. ---
**Author:** ![Nemo157](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nemo157/32/11585_2.png) [@Nemo157](https://internals.rust-lang.org/u/Nemo157)\ **Post date:** [March 20, 2023, 6:45pm UTC](https://internals.rust-lang.org/t/can-the-standard-library-please-ban-println-and-similar-functions-from-doctests/18534/23 "2023-03-20T18:45:31Z")
Rustdoc does not run tests during doc generation, so it could include the _expected_ output, but not prove that the test is actually passing (which I guess is similar to the existing should-panic/no-compile annotations that assume they are correct). ---
**Author:** ![steffahn](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steffahn/32/13288_2.png) [@steffahn](https://internals.rust-lang.org/u/steffahn)\ **Post date:** [March 21, 2023, 12:46am UTC](https://internals.rust-lang.org/t/can-the-standard-library-please-ban-println-and-similar-functions-from-doctests/18534/24 "2023-03-21T00:46:15Z")
I feel like the whole _point_ of the documentation example with the `print!` in a call to `.map` is _not at all_ to demonstrate the precise behavior of the particular code in question. Instead, it's point is actually to talk about a whole _pattern_ of code, the pattern being `ITERATOR.map(|VAR| EFFECTFUL_ACTION(VAR));`, and it explains that this pattern of code will not have the desired effect and that `for VAR in ITERATOR { EFFECTFUL_ACTION(VAR) }` should be used instead. Since writing this in full generality, with metavariables for the iterator, variable name, and action, would probably be too abstract and thus confusing, some minimal concrete examples are used instead and they implicitly _stand for_ the general case. All of `0..5`, `x`, and `print!("{x}")` are short, non confusing, trivially simple to understand, and very clearly an instance of the thing they stand for, namely, an iterator, a variable, and an effectful action, respectively. Any additional complication added to make the completely uninteresting behavior of this code more machine-testable would only _obfuscate_ this intent. Especially if the approaches suggested above were taken, introducing additional mutable variables into the context and modifying them in the `.map` and the loop, that would quickly and unnecessarily overcomplicate things. Suddenly, you would need to start thinking about the behavior of some loop with mutable state, which would take the focus from the main point of this example. ---
**Author:** ![jhpratt](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jhpratt/32/11640_2.png) [@jhpratt](https://internals.rust-lang.org/u/jhpratt)\ **Post date:** [March 21, 2023, 2:22am UTC](https://internals.rust-lang.org/t/can-the-standard-library-please-ban-println-and-similar-functions-from-doctests/18534/25 "2023-03-21T02:22:43Z")
Suggestion: Instead of `println!`, use `nuke_mars()`. Make it clear that it has side effects 😉 ---
**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\ **Post date:** [June 19, 2023, 2:23am UTC](https://internals.rust-lang.org/t/can-the-standard-library-please-ban-println-and-similar-functions-from-doctests/18534/26 "2023-06-19T02:23:09Z")
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed. [Previous page](https://internals.rust-lang.org/t/can-the-standard-library-please-ban-println-and-similar-functions-from-doctests/18534.md?page=1)