Attribute Macro doc_item::docbox [−][src]
#[docbox]
Adds a docbox to the item’s item-info.
A docbox is defined to be a box below the item’s definition within documentation, alerting the user to important information about the item. A common use case is to alert about an experimental item. This can be done as follows:
#[doc_item::docbox(content="This API is experimental", class="unstable")] pub fn foo() {}
Custom Styles
The docbox can be styled using the class
parameter. The class corresponds to a CSS class in
the generated HTML. In the above example, "unstable"
was used, as it is already a predefined
class by rustdoc. Other predefined classes include "portability"
and "deprecated"
. If
different style is desired, a custom class can be provided using the --html-in-header
rustdoc
flag.
Provide a custom class like this:
#[doc_item::docbox(content="A custom docbox", class="custom")] pub fn foo() {}
Define the custom class in a separate file, potentially named custom.html
.
<style>
.custom {
background: #f5ffd6;
border-color: #b9ff00;
}
</style>
And finally build the documentation with the custom docbox class.
$ RUSTDOCFLAGS="--html-in-header custom.html" cargo doc --no-deps --open
Multiple Docboxes
Multiple docbox attributes may be used on a single item. When generating the documentation,
doc_item
will insert the docboxes in the reverse order that they are provided in. For
example:
#[doc_item::docbox(content="This box will display second", class="unstable")] #[doc_item::docbox(content="This box will display first", class="portability")] pub fn foo() {}
will result in the "portability"
docbox being displayed above the "unstable"
docbox.