Struct field documentation and #[cfg(...)

[hannobraun]

Consider the following code:

#[deny(missing_docs)]

/// A struct
pub struct Struct {
    /// A field
    #[cfg(feature = "feature")]
    pub field: u32,
    #[cfg(not(feature = "feature"))]
    pub field: u64,
}

I would expect this to compile in any configuration. Only one version of field can ever exist. The doc comment should apply to the version of field that is being compiled.

However, if I compile this (without specifying any features), it fails:

error: missing documentation for a struct field
 --> src/lib.rs:9:5
  |
9 |     pub field: u64,
  |     ^^^^^^^^^^^^^^
  |
note: lint level defined here
 --> src/lib.rs:1:8
  |
1 | #[deny(missing_docs)]
  |        ^^^^^^^^^^^^

If I specify feature, it builds without problems:

$ cargo build --features feature
   Compiling field-cfg-doc v0.1.0 (file:///home/hanno/tmp/Projects/field-cfg-doc)
    Finished dev [unoptimized + debuginfo] target(s) in 0.12 secs

cargo doc's behavior is consistent with the behavior of the compiler. It only picks up the doc comment, if feature is specified (cargo doc --features feature).

This is the nightly version I'm using:

$ rustc --version --verbose
rustc 1.22.0-nightly (f6d751454 2017-10-17)
binary: rustc
commit-hash: f6d7514545cbe83e771a400d04049b96dfb210cd
commit-date: 2017-10-17
host: x86_64-unknown-linux-gnu
release: 1.22.0-nightly
LLVM version: 4.0

But I'm also seeing this on stable:

$ rustc --version --verbose
rustc 1.21.0 (3b72af97e 2017-10-09)
binary: rustc
commit-hash: 3b72af97e42989b2fe104d8edbaee123cdf7c58f
commit-date: 2017-10-09
host: x86_64-unknown-linux-gnu
release: 1.21.0
LLVM version: 4.0

Here's a repository with an example Cargo project that can be used to reproduce this problem: https://github.com/hannobraun/field-cfg-doc

[kennytm]

It is working as expected. The doc-comment is only attached to field: u32. If you don't supply the feature, the field alongside the doc-comment will be removed. If you need to retain the doc-comment in both configurations, duplicate it.

#[deny(missing_docs)]

/// A struct
pub struct Struct {
    /// A field
    #[cfg(feature = "feature")]
    pub field: u32,
    /// A field
    #[cfg(not(feature = "feature"))]
    pub field: u64,
}

[hannobraun]

It is working as expected.

Hmm, that's what I feared.

If you need to retain the doc-comment in both configurations, duplicate it.

I encountered this problem in a situation where it's important for the user to know that the field can appear in different versions. Hence, both versions of the documentation need to reference both versions of the field. Which means, I effectively need the same doc comment twice.

Probably not a big deal though. Thanks for your reply!

[kennytm]

@hannobraun If all those fields only differ by u32 vs u64, you could define a common type alias, so you only need to document the field once:

/// SomeType is u32 when feature is on, and u64 when feature is off.
#[cfg(feature = "feature")]
pub type SomeType = u32;
/// SomeType is u32 when feature is on, and u64 when feature is off.
#[cfg(not(feature = "feature"))]
pub type SomeType = u64;

/// A struct
pub struct Struct {
    /// A field
    pub field: SomeType,
}

[hannobraun]

@kennytm Oh, that's a neat idea! The u32/u64 thing was just for the sake of example, but your technique could apply to my real-life problem anyway. Thank you!