Rust specific roles

The extension provides the following roles, which can be referenced as :<role_name>:. For all roles, the target is the double colon (::) delimited full Rust path to the item, similar to the path used when importing the item. This syntax is slightly extended to accommodate linking to trait impl blocks and fields within a struct.

For all importable items like structs, enums, traits, etc., the target path is the Rust import path, either <crate_name>::<module_name>::<item> or <executable_name>::<module_name>::<item>. For referencing implementations of a trait or items within a trait impl, the link target is provided as <crate_name>::<module_name>::<item>::<trait_name>::<trait_item>.

More details are described below.

For all roles, adding a ~ before the path will display only the final portion of the path as the link text. So, :rust:fn:`~crate::module::func` will display only func as the link text.

:rust:crate:

:rust:crate:`<crate_name>` links to the crate’s documentation, within lib.rs.

:rust:enum:

:rust:enum:`<enum_path>` links to an enum’s documentation. Specific variant’s within the enum can be referenced using the struct role.

:rust:exe:

:rust:exe:`<executable_name>` links to an executable’s documentation.

:rust:executable:

Alias for rust:exe.

:rust:fn:

:rust:fn:`<fn_path>` links to a function’s documentation.

To a reference a function, use the full path to the impl block where the function is defined, followed by the function’s name. See the rust:impl documentation below for details.

Note that the path <trait_path>::<fn> references the function declaration within the trait, whereas <struct_path>::<trait>::<fn> references the implementation of the trait’s function for the struct.

:rust:function:

Alias for rust:fn.

:rust:impl:

:rust:impl:`<impl_path>` links to an impl block, either of the struct, or for a trait for a struct. The <impl_path> is provided as <crate_name>::<module_name>::<item> for struct or enum impl blocks and as <crate_name>::<module_name>::<item>::<trait_name> for trait impl blocks.

When referencing an impl block for a struct or an enum, use the full path to the impl block within the crate. So, if the impl Foo block is in a different module from the struct itself, the path must reference the module of the impl block. Items within the impl block like functions and variables are then nested under this path.

When referencing a trait impl block, the last two components of the path are <item>::<trait>. So, a block impl Display for Foo is referenced as crate::module::Foo::Display.

:rust:macro:

:rust:macro:`<macro_path>` inks to a macro’s documentation.

:rust:module:

:rust:module:`<module_path>` inks to the module’s documentation. The module path here is the Rust path of the module, not its file’s path.

:rust:struct:

:rust:struct:`<struct_path>` links to a struct or an enum variant’s documentation. For an enum variant, use :rust:struct:`<enum_path>::<variant>` as the target.

Specific fields within the struct or variant can be referenced using the rust:variable role.

:rust:trait:

:rust:trait:`<trait_path>` links to a trait’s documentation. Items defined within the trait are nested under the trait’s path.

:rust:type:

:rust:type:`<type_path>` links to a type’s documentation.

:rust:variable:

:rust:variable:`<variable_path>` links to a static or const variable, or to a field within a struct or enum variant.

For fields of a struct, the path is <struct_path>::<field_name>, For tuple structs, the field’s index should be used instead of the name. For an enum variant’s fields, the path is <enum_path>::<variant>::<field_name>, with field index instead of name for tuple variants.

:rust:var:

Alias for rust:variable.