Microseries platform and Studio aTwist launched today (September 3) complete with a slate of 10 original series including the first foray into the vertical drama space from The Bold and the Beautiful’...

bradbell: > a huge number of items below `Auto Trait Implementations` and `Blanket Implementations` . How to I suppress these automatically generate items first of all, these sections are placed at the last position, after the manual trait `impl`s, in order to make them less intrusive. auto traits are all one-liners because they are marker traits, and the blanket `impl`s are wrapped in `<details>` html tags and collapsed on load, so I don't think suppressing these sections makes a significant difference in terms of readability. but if you insist, you can use css to hide them, it's just html after all. (I don't think you can prevent `rustdoc` from generating them, though). there's an `--extend-css` command line option for this. this will append the custom css to all the theme css files. alternatively, you can also use a custom theme (with the `--theme` command line option), instead of modifying the existing ones, so you can toggle the visibility by simply switching themes. however, the format of `rustdoc` output is undocumented, the relevant `id` and `class` of the html elements can only be found in the source code. for example, the section of auto trait implementations and blanket implementations are rendered here: github.com/rust-lang/rust #### src/librustdoc/html/render/mod.rs `8a407a828` 1292. if !synthetic.is_empty() { 1293. write!( 1294. w, 1295. "{}<div id=\"synthetic-implementations-list\">", 1296. write_impl_section_heading("Auto Trait Implementations", "synthetic-implementations",) 1297. ) 1298. .unwrap(); 1299. render_impls(cx, &mut w, synthetic, containing_item, false); 1300. w.write_str("</div>").unwrap(); 1301. } 1302. 1303. if !blanket_impl.is_empty() { 1304. write!( 1305. w, 1306. "{}<div id=\"blanket-implementations-list\">", 1307. write_impl_section_heading("Blanket Implementations", "blanket-implementations") 1308. ) 1309. .unwrap(); 1310. render_impls(cx, &mut w, blanket_impl, containing_item, false); 1311. w.write_str("</div>").unwrap(); 1312. }

bradbell: > How do I do this ? Assuming you want the docs.rs docs to be the user-facing docs, i.e. hide the module from these docs, you can add the following to your `Cargo.toml`: [package.metadata.docs.rs] rustdoc-args = ["--cfg", "docsrs"] to add the `docsrs` conditional compilation flag to docs.rs builds of your documentation. Then, hide the module from the docs if the `docsrs` flag is enabled: #[cfg_attr(docsrs, doc(hidden))] mod foo; This is not specific to docs.rs, you can use compiler flags or Cargo features in a way that suits your doc build pipeline.

bradbell: > * How does one get the location of the current page, relative to the entire documentation tree, on the left side margin and the headings within the current page on the right side margin. For example; see > begin_cmd - xrst documentation > Not sure, but you may be looking for how to reference and link to a module, which links to the top of the page for that module. That's done with `[module-path]`. For example, `[self]` will link to the current module. See https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html bradbell: > * How does one have two levels of documentation. One, for uses, that defines the package API and that just links within itself. Another, for developers, that automatically includes and can link to all the user documentation. > Other than the answer below, I don't know of any options for this. bradbell: > How does one turn off the documentation of some public items (that are not part of the user API) when building the user documentation and turn it on when building the developer documentation. With `--document-private-items`. See https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden

I posted the following issue: github.com/alekseysidorov/include-utils #### Anchors not working in rust source files opened 01:31PM - 29 May 25 UTC bradbell To reproduce this problem store the following file as `include.sh` and then exec…ute `./include.sh` : ``` #! /usr/bin/env bash set -e -u if [ -e hello-world ] then rm -r hello-world fi cargo new hello-world cd hello-world cargo add include-utils cat << EOF > src/main.rs use include_utils; /// Hello World /// ''' #[doc = include_utils::include_md!("src/main.rs:main")] /// ''' /// // ANCHOR: main fn main() { println!("Hello, world!"); } // ANCHOR_END: main EOF cargo doc echo 'include.sh: OK' exit 0 ``` Output that I get: ``` Creating binary (application) `hello-world` package note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html Updating crates.io index Adding include-utils v0.2.4 to dependencies Features: - workspace Updating crates.io index Locking 12 packages to latest Rust 1.87.0 compatible versions Compiling proc-macro2 v1.0.95 Checking unicode-ident v1.0.18 Compiling smallvec v1.15.0 Documenting unicode-ident v1.0.18 Documenting smallvec v1.15.0 Compiling either v1.15.0 Documenting either v1.15.0 Compiling itertools v0.13.0 Documenting itertools v0.13.0 Documenting proc-macro2 v1.0.95 Checking quote v1.0.40 Checking proc-macro-utils v0.10.0 Checking syn v2.0.101 Documenting quote v1.0.40 Documenting proc-macro-utils v0.10.0 Documenting syn v2.0.101 Compiling manyhow-macros v0.11.4 Documenting manyhow-macros v0.11.4 Checking manyhow v0.11.4 Documenting manyhow v0.11.4 Compiling include-utils-macro v0.2.4 Checking include-utils v0.2.4 Documenting include-utils-macro v0.2.4 Documenting include-utils v0.2.4 Documenting hello-world v0.1.0 (/Users/bradbell/trash/rust/hello-world) error: Included file doesn't contain anchor with name: main --> src/main.rs:5:9 | 5 | #[doc = include_utils::include_md!("src/main.rs:main")] | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | = note: this error originates in the macro `include_utils::include_md` (in Nightly builds, run with -Z macro-backtrace for more info) error: could not document `hello-world` ```

bradbell: > Does this mean that the option is still unstable That seems the case. bradbell: > and will probably not become a normal option ? I wouldn't go as far. It's probably just that this hasn't received as much love.

If you are using rustup, you can also use the toolchain override flag: `cargo +nightly ...` to switch from your default to the nightly toolchain. * * * bradbell: > option is still unstable Yes. bradbell: > not become a normal option I don't think so, this one looks to me like it will be stabilised eventually. But stabilisation takes time, effort and feedback from the users, all being scarce sometimes in open source.

bradbell: > 1. Can be run as tests to make sure they still work. > If you put the large examples in `examples/`1], Cargo will automatically treat them as [example targets. You can run them as tests with `cargo test --examples` or `cargo test --all-targets`. * * * bradbell: > 2. Do not have /// at the start of each line. > 3. Will be part of the documentation with supporting text that explains them. > You can manually import them with `include_str!`, e.g.: /// ``` #[doc = include_str!("../examples/foo.rs")] /// ``` pub struct Foo; * * * 1. Or make them otherwise accessible to Cargo via the manifest. ↩︎

bradbell: > error: the `-Z` flag is only accepted on the nightly channel of Cargo, but this is the `stable` channel > `https://doc.rust-lang.org/book/appendix-07-nightly-rust.html` The error message is pointing you to the solution. You might be used to error messages not being helpful, but in Rust they usually point you in the right direction. That being said, you need to use the `nightly` channel of compiler, so all you need to do is this (assuming you're using rustup and you have installed the nightly channel): rustup override set nightly If you haven't installed the nightly release channel, you'll have to do this before running the command above: rustup toolchain install nightly

When you use `thread_local`, you do not actually get an item of the specified type, you get an item of type `LocalKey<_>`. You have to use the methods of `LocalKey` to reach the actual value. bradbell: > 2. If you remove the // below, why does it not compile ? > To get `&RefCell` from the `LocalKey`, you have to use `with()`. VEC.with(|tl_vec| { tl_vec.borrow_mut().push(3.0); }); Or, there is also a combined version specifically for `LocalKey<RefCell<_>>`: VEC.with_borrow_mut(|tl_vec| { tl_vec.push(3.0); }); This callback pattern gives a couple of stronger guarantees than just returning a reference does: * It guarantees that the reference cannot outlive this specific call, which is necessary for soundness here, because otherwise you could take a reference to a thread-local, send it to another thread, wait for the thread to terminate, and end up with a dangling reference. * It guarantees that `with()` can run cleanup code after the callback function finishes. This doesn’t actually matter here, but it is critical for other uses of this callback pattern like `std::thread::scope()`. bradbell: > 1. Why does this program print `LocalKey{ .. }` instead of the same output > as the line above ? > Because that's what `LocalKey`’s `Debug` implementation does. Why? I don’t know exactly. Perhaps there could be a problematic situation if the value is not yet initialized. You'll need to call `with()` before printing.

bradbell: > Is there a `where` clause that would make it work for all types that could convert from the integer value 3 to the type T ? It's actually a `{float}` value - either `f32` or `f64` - since the value is `3.0` and not `3`. In either case, though, yes, there is: fn generic_push_3<T>(v: &mut Vec<T>) where T: From<f64> { v.push(T::from(3.0)); } You can also write the innermost conversion as `(3.0).into()`, if you prefer; `Into` has a blanket implementation based on `From`. For complicated reasons, there isn't a numeric tower of types in Rust, so there's no type or trait that is implemented by all integers or by all floating point types. There are crates that provide that, if you want something more general, but working with the specific numeric type of interest, non-generically, is usually good enough.

bradbell: > In C++, the compiler determines (at compile time) that the usage is valid for all the cases that use it. C++ doesn't have generics at all, it only have templates – thus it's useless to say what C++ does. It's entirely different thing which is only very superficially similar to generics. Ada, Java, C#, Go, Haskell and all other languages that **do** have generics work more-or-less like Rust does. bradbell: > Is there a `where` clause that would make it work for all types that could convert from the integer value 3 to the type T ? No, because there are not “integer value 3” type. You may ask for a type to be constructible from `i8` (`i8: Into<T>`) – but then `u8` wouldn't be supported. Or you may ask for a type to be constructible from `u8`(`i8: Into<T>`) – but then `i8` wouldn't be supported. It's known that writing generic numerical computation code in Rust is real PITA, people usually just go with macros to implement them and not with generics.

On Thursday June 11, it was announced that The Bold and the Beautiful’s Bradley Bell (executive producer and head writer) is getting into the burgeoning vertical space, and will bring his first micros...

ALT: a man in a suit and tie says " no perverts ! "