Documentación con rustdoc
03/07/2017
La documentación es una parte importante y muchas veces olvidada de un proyecto de software. Rust cuenta desde el principio con una herramienta destinada a que escribir documentación sea poco doloroso, se trata de rustdoc.
Los comentarios de rustdoc empiezan con 3 barras y pueden llevar Markdown. Se escriben encima de la función, estructura, etc que describamos.
Mencionar que el código del comentario es sometido a tests también por cargo test. Para generar la documentación basta con escribir cargo doc y Cargo generará la documentación en formato HTML.
El mejor sitio para leer la documentación de Rust es Docs.rs. Docs.rs ejecuta cargo doc a todas las crates de Crates.io y las expone al público sin costo.
Comentarios en Markdown
Los comentarios de rustdoc empiezan con 3 barras y pueden llevar Markdown. Se escriben encima de la función, estructura, etc que describamos.
/// Perfil almacena los datos del perfil de un usuario en nuestra webapp
struct Perfil{
username: String,
password: String,
url: Option<String>
}
impl Perfil{
/// Genera un nuevo Perfil
/// # Ejemplo
/// ```
/// let user = Perfil::new("The42","1234");
/// ```
pub fn new(u: &str, p: &str) -> Perfil{
Perfil {username: String::from(u), password: String::from(p), url: None}
}
}
Mencionar que el código del comentario es sometido a tests también por cargo test. Para generar la documentación basta con escribir cargo doc y Cargo generará la documentación en formato HTML.
Consultando documentación
El mejor sitio para leer la documentación de Rust es Docs.rs. Docs.rs ejecuta cargo doc a todas las crates de Crates.io y las expone al público sin costo.
