Doc attributes

We mentioned that the doc comments that we write get converted into doc attributes form. Apart from those, there are other doc attributes for documentation that can tweak the generated documentation page, and these are applied either at the crate level or at the item level. They are written like #[doc(key = value)]. Some of the most useful doc attributes are as follows:

Crate-level attributes:

  • #![doc(html_logo_url = "image url"): Allows you to add a logo to the top-left of your documentation page.
  • #![doc(html_root_url = "https://docs.rs/slotmap/0.2.1")]: Allows you to set the URL for the documentation page.

  • #![doc(html_playground_url = "https://play.rust-lang.org/")]: Allows you to put a run button near the code example in your documentation so that you can run it directly in the online Rust playground.

Item-level attributes:

  • #[doc(hidden)]: Say you have written the documentation for a public function, foo, as a note to yourself. However, you don't want your consumers to view the documentation. You can use this attribute to tell rustdoc to ignore generating docs for foo.
  • #[doc(include)]: This can be used to include documentation from other files. This helps you separate your documentation from code if it's really long.

For more attributes like these ones, head over to https://doc.rust-lang.org/beta/rustdoc/the-doc-attribute.html.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset