Anonymous user
Documentation: Difference between revisions
Add a Rust solution
(Add a Rust solution) |
|||
Line 1,455:
# :include:boilerplate.txt</lang>
=={{header|Rust}}==
Rust code is documented using the <code>rustdoc</code> tool included with the compiler (typically as <code>cargo doc</code>), which combines information from two sources: Automatic API documentation harvested from type signatures, and manual documentation provided by annotating the code with snippets of Markdown.
[https://doc.rust-lang.org/std/string/struct.String.html The Rust standard library documentation] serves as an example of what locally generated documentation looks like, but many people rely instead on the [https://docs.rs/ docs.rs] service, which generates and hosts documentation for crates published on [https://crates.io/ crates.io].
The rust toolchain also takes responsibility for running code blocks within the documentation as part of the project's test suite, ensuring that they will remain up-to-date with the code they exercise.
Documentation annotations are [https://doc.rust-lang.org/rustdoc/the-doc-attribute.html implemented] as standard block attributes, but the Rust toolchain allows them to take four forms:
* <code>#[doc = "string"]</code> and <code>#![doc = "string"]</code> define a documentation string using Rust's standard attribute syntax. The former syntax documents the function, struct, or other object immediately following, while the latter syntax is used to document the module it appears within.
* <code>#[doc(...)]</code> and <code>#![doc(...)]</code> are another variant of of the standard Rust attribute syntax, which are used to specify metadata such as the favicon URL to use when generating HTML documentation and whether an item should be excluded from the docs.
* <code>/// string</code> and <code>/** string */</code> are syntactic sugar for <code>#[doc = "string"]</code> and are the typical way to document everything except modules corresponding to files.
* <code>//! string</code> and <code>/*! string */</code> are syntactic sugar for <code>#![doc = "string"]</code> and are the typical way to document modules corresponding to files, as there is no way to place a documentation annotation before the beginning of a file.
Rustdoc will not generate documentation for private members of crates by default, but this can be changed by calling it with the <code>--document-private-items</code> flag. (For example, using <code>cargo doc --document-private-items</code> to generate documentation for the internals of a crate which generates an executable rather than a library.)
Here's an example of some heavily documented mock code:
<lang rust>//! Documentation for the module
//!
//! **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Aenean a
//! sagittis sapien, eu pellentesque ex. Nulla facilisi. Praesent eget sapien
//! sollicitudin, laoreet ipsum at, fringilla augue. In hac habitasse platea
//! dictumst. Nunc in neque sed magna suscipit mattis sed quis mi. Curabitur
//! quis mi a ante mollis commodo. Sed tincidunt ut metus vel accumsan.
#![doc(html_favicon_url = "https://example.com/favicon.ico")]
#![doc(html_logo_url = "https://example.com/logo.png")]
/// Documentation for a constant
pub const THINGY: u32 = 42;
/// Documentation for a Rust `enum` (tagged union)
pub enum Whatsit {
/// Documentation for the `Yo` variant
Yo(Whatchamabob),
/// Documentation for the `HoHo` variant
HoHo,
}
/// Documentation for a data structure
pub struct Whatchamabob {
/// Doodads do dad
pub doodad: f64,
/// Whether or not this is a thingamabob
pub thingamabob: bool
}
/// Documentation for a trait (interface)
pub trait Frobnify {
/// `Frobnify` something
fn frob(&self);
}
/// Documentation specific to this struct's implementation of `Frobnify`
impl Frobnify for Whatchamabob {
/// `Frobnify` the `Whatchamabob`
fn frob(&self) {
println!("Frobbed: {}", self.doodad);
}
}
/// Documentation for a function
///
/// Pellentesque sodales lacus nisi, in malesuada lectus vestibulum eget.
/// Integer rhoncus imperdiet justo. Pellentesque egestas sem ac
/// consectetur suscipit. Maecenas tempus dignissim purus, eu tincidunt mi
/// tincidunt id. Morbi ac laoreet erat, eu ultricies neque. Fusce molestie
/// urna quis nisl condimentum, sit amet fringilla nunc ornare. Pellentesque
/// vestibulum ac nibh eu accumsan. In ornare orci at rhoncus finibus. Donec
/// sed ipsum ex. Pellentesque ante nisl, pharetra id purus auctor, euismod
/// semper erat. Nunc sit amet eros elit.
pub fn main() {
let foo = Whatchamabob{ doodad: 1.2, thingamabob: false };
foo.frob();
}</lang>
=={{header|Scala}}==
| |||