Doctest of private functions

[michaelhugi]

Hello

I am currently documenting a lot. I also want to document private functions and use doctest for that.

I understand that the example will not work when used outside of scope, but I will not build documentation for functions that are private. Anyway I want to document them properly. The compiler complains that the method is private in my documentation.

Is there a way to tell the compiler that documentation on private methods should ignore that used methods are private?

Here a code example:

///removes the upper half of a byte.
    /// ```rust
    /// use gdtf_parser::utils::units::guid::FixtureTypeGuid;
    /// assert_eq!(FixtureTypeGuid::get_lower_halfbyte(0b0000_0100).unwrap(),0b0000_0100);
    /// assert_eq!(FixtureTypeGuid::get_lower_halfbyte(0b0010_1100).unwrap(),0b0000_1100);
    /// ```
    pub(crate) fn get_lower_halfbyte(byte: u8) -> Result<u8, GdtfGuidError> {
        let s1 = if Self::is_byte_one_at_index(byte, 4)? { 0b0000_1000_u8 } else { 0 };
        let s2 = if Self::is_byte_one_at_index(byte, 5)? { 0b0000_0100_u8 } else { 0 };
        let s3 = if Self::is_byte_one_at_index(byte, 6)? { 0b0000_0010_u8 } else { 0 };
        let s4 = if Self::is_byte_one_at_index(byte, 7)? { 0b0000_0001_u8 } else { 0 };
        Ok(s1 + s2 + s3 + s4)
    }

[mbrubeck]

Doctests are built by first compiling your library normally, and then compiling each doctest as a separate binary crate that links to that library. The doctest can't access private functions, for the same reason any other crate can't: The library doesn't export any symbols for them, so there's no way to call them from outside.

Only unit tests can access private items, because the unit tests and the code they are testing are all compiled as a single crate.

[michaelhugi]

@mbrubeck

crate

Makes sence
Thanks

[quinedot]

You can ignore them too, but they won't be verified to compile and they'll document examples consumers of the library can't do.

[Yandros]

You can use the ::visibility crate to assist you with this:

visibility

@README.md

#[visibility::make]

Attribute to override the visibility of items (especially useful in conjunction with #[cfg_attr(…)]).

Since it is currently not possible to conditionally modify the visibility of an item, but since it is possible to conditionally apply an attribute, this crate features a trivial attribute that modifies the visibility of the decorated item.

This way, by conditionally applying it, one can achieve the desired goal:

Example

/// Some fancy docs.
///
/// ## Example
///
/// ```rust
/// ::my_crate::module::foo();
/// ```
// Assuming `cargo test --doc --features integration-tests` is run:
#[cfg_attr(feature = "integration-tests", visibility::make(pub))]
mod module {
    pub fn foo() {}
}

After having added visibility as an optional dependency and having defined an integration-tests feature that enables it:

[dependencies]
visibility.version = "x.y.z"
visibility.optional = true

[features]
integration-tests = ["visibility"]