`doc(cfg(a or b or c) and a)` should cut unnecessary conditions

[ventaquil]

I tried this code:

#[doc(
    cfg(
        any(
            feature = "a",
            feature = "b",
            feature = "c",
        )
    )
)]
#[doc(
    cfg(
        feature = "a",
    )
)]
pub fn add(left: usize, right: usize) -> usize {
    left + right
}

I expected to see this happen after creating documentation:

Available on crate feature a only.

Instead, this happened:

Available on (crate features a or b or c) and crate feature a only.

Occured when one module requires any of few features and then submodules requires one of those features - module should list create features a or b or c but submodule should return only create feature a.

Meta

rustc --version --verbose:

rustc 1.67.0-nightly (a00f8ba7f 2022-11-15)
binary: rustc
commit-hash: a00f8ba7fcac1b27341679c51bf5a3271fa82df3
commit-date: 2022-11-15
host: x86_64-unknown-linux-gnu
release: 1.67.0-nightly
LLVM version: 15.0.4

[fmease]

@rustbot label T-rustdoc F-doc_cfg

(note that you typo'ed doc(cfg as cfg(doc(cfg in your reproducer)

[ventaquil]

Oh, agree 👍

My fault, original version was with cfg_attr(docsrs, doc(...)) and copy-paste-delete in the middle of night needs more checks against bugs 🐛

[ventaquil]

Also when I have feature that enables all of a, b and c together, name it just abc.

[features]
a = []
b = []
c = []
abc = ["a", "b", "c"]

Then

#[doc(
    cfg(
        feature = "abc",
    )
)]
pub mod abc {
    #[doc(
        cfg(
            feature = "a",
        )
    )]
    pub mod a {
        // ...
    }
}

It will produce.

Available on crate feature abc and crate feature a only.

Maybe it should return just it.

Available on crate feature a only.

[jyn514]

Note this is a major expansion of scope, it requires a full SMT solver.

[est31]

It is correct that it's an expansion of scope, but it seems that SMT solvers aren't enough for this: I am currently still reading the literature but it seems it's not even in NP (like SMT) but is Σ^P₂ - complete (a complexity class above NP).

The links I could find all relied on brute force which can be used less complex formulas but of course doesn't help with more complex ones:

• https://babbage.cs.qc.cuny.edu/courses/Minimize/
• https://research.swtch.com/boolean talks about a brute force approach that might be useful for small numbers of literals

For, SMT solvers there exist really performant Rust implementations, so we could just have used them as a library, but seems here we can't use them.

That being said, rustdoc is putting these notices all over the place so one should at least expect it to be able to do simple minimizations of the formula even if those don't arrive at the maximum possible level of minimization. Yes, it requires heavily algorithmic work. But the general skillset is present in Rust, and rustc is doing a lot of algorithmic stuff already in the type and borrow checkers (among others).

[jyn514]

I am very concerned about adding large new features like that in rustdoc, especially without an RFC. The people working on the compiler are not the same people working on rustdoc (and historically it's been very hard to get the two to share knowledge).

[est31]

Fair points on the two groups of people being different. As for needing an RFC, a transformation of the form (a or b or c) and a -> (b or c) and a is trivial to implement, this shouldn't need an RFC imo. The Cargo.toml thing is harder as rustdoc would need the information about features implying each other passed to it via params. That might need an RFC indeed.

[ventaquil]

Referring to WolframAlpha (a or b or c) and a should return just a.

https://www.wolframalpha.com/input?i=simplify+%28a+or+b+or+c%29+and+a

[est31]

oh right good point. if a is false, then it's false, and if a is true then it's true. Anyways, it's easy to implement a few rules like these and apply them until a fix point is reached.

[Kixunil]

Wouldn't it be better to issue a warning in cases like this that some conditions do nothing? If someone wrote such condition it seems more likely it wasn't intended to contain contradictions or unused conditions. "Only for simple cases" still applies.

[est31]

I think it would be a good idea to have both, and have the doc elimination be a bit more aggressive than the warning. For example, you could have sth like:

#[cfg(any(feature = "foo", feature = "bar", feature = "baz"))]
pub mod hi {
    // Something common to feature foo, bar and baz
    
    // Something only bar has
    #[cfg(feature = "bar")]
    pub fn bar_only () {}
}

Here, without simplifications, bar_only would have doc(cfg(and(any(foo, bar, baz), bar)) which could be simplified to doc(cfg(bar)). But you shouldn't warn about it, because hi might contain other code that is common to bar, foo and baz, and bar_only might really be limited to bar.