Search code examples
rustdocumentation

Can you use a const value in docs in Rust?

Can you use a const's value in documentation in rust? Something like string interpolation to insert a value:

const EXPIRATION_TIME_IN_MINUTES: i64 = 60*24;

/// A struct that does something
/// Whatever this struct does, it expires in ${EXPIRATION_TIME_IN_MINUTES} minutes. 
struct SomeStruct {
   ...
}

The proposed use case is exactly this, documenting what the default setting for expiration for a function.

Solution

  • Typical documentation that references a constant would do it by adding documentation in two places and linking them together:

    /// The expiration time used for instances of `SomeStruct`, in minutes.
const EXPIRATION_TIME_IN_MINUTES: i64 = 60 * 24;

/// A struct that does something. The expiration associated with this struct 
/// is given by the constant [`EXPIRATION_TIME_IN_MINUTES`].
struct SomeStruct {
   ...
}

    Even though the value of the constant will not appear inline, using [``] will create a hyperlink to the docs for the constant so a user can see the value there.