Doctest of private functions


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)

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.

1 Like

Makes sence

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.

1 Like

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

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

visibility.version = "x.y.z"
visibility.optional = true

integration-tests = ["visibility"]
1 Like

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.