Doc comments only apply to the first #[cfg] item, even if another is ultimately selected.

[umanwizard]

Given the following code:

#![warn(missing_docs)]
//! my test crate

/// foo.
#[cfg(debug_assertions)]
pub const FOO: () = ();
#[cfg(not(debug_assertions))]
pub const FOO: () = ();

fn main() {}

The current output is:

warning: missing documentation for a constant
 --> src/main.rs:8:1
  |
8 | pub const FOO: () = ();
  | ^^^^^^^^^^^^^^^^^^^^^^^
  |
note: the lint level is defined here
 --> src/main.rs:1:9
  |
1 | #![warn(missing_docs)]
  |         ^^^^^^^^^^^^

warning: `test_rust` (bin "test_rust") generated 1 warning
    Finished release [optimized] target(s) in 0.00s

The above is only seen on release builds; on debug builds, no warning is output.

The doc comment should apply to whichever piece of code is actually compiled. Is there a way to achieve this without duplicating the comment?

[umanwizard]

Maybe a dupe of #1998

[jyn514]

@umanwizard you seem to be imagining that doc-comments apply like this (using braces to mean precedence since rust doesn't have a syntax for this):

/// foo.
{
  #[cfg(debug_assertions)]
  pub const FOO: () = ();
  #[cfg(not(debug_assertions))]
  pub const FOO: () = ();
}

But they don't - they apply like this:

{
  // foo.
  #[cfg(debug_assertions)]
  pub const FOO: () = ();
}
{
  #[cfg(not(debug_assertions))]
  pub const FOO: () = ();
}

The doc-comment is just another attribute - you could also write it as #[doc = " foo."] if you like. For consistency, it behaves the same as any other attribute in that position.

If you want to share the docs between two items, you could put them in an extern file and use #[doc = include_str!("my_docs.md")] above both items.

[umanwizard]

For posterity, I ended up solving it like this:

MaterializeInc/materialize#9238