From bb0c9d8906694be2c7830b4140fa742f3f51b41a Mon Sep 17 00:00:00 2001 From: Rasmus Kaj Date: Sun, 16 Jul 2023 23:00:43 +0200 Subject: [PATCH] Improve documentation. Mainly get rid of some very old workarounds for limitations in early cargo doc. --- src/Template_syntax.rs | 6 +++--- src/lib.rs | 18 +++++------------- src/templates/utils_warp03.rs | 13 ++++++++----- 3 files changed, 16 insertions(+), 21 deletions(-) diff --git a/src/Template_syntax.rs b/src/Template_syntax.rs index c84195b..90fdf70 100644 --- a/src/Template_syntax.rs +++ b/src/Template_syntax.rs @@ -55,14 +55,14 @@ //! //! The curly brackets, `{` and `}`, is used for blocks (see Loops, //! Conditionals, and Calling other templates below). - +//! //! To use verbatim curly brackets in the template body, they must be //! escaped as `@{` and `@}`, the same goes for the `@` sign, that //! precedes expressions and special blocks; verbtim `@` signs must be //! escaped as `@@`. //! -//! [`ToHtml`]: ../templates/trait.ToHtml.html -//! [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html +//! [`ToHtml`]: crate::templates::ToHtml +//! [`Display`]: std::fmt::Display #![allow(non_snake_case)] pub mod a_Value_expressions { diff --git a/src/lib.rs b/src/lib.rs index 671b649..255285d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -14,7 +14,7 @@ //! //! The template syntax, which is inspired by [Twirl], the Scala-based //! template engine in [Play framework], is documented in -//! [the _Template syntax_ module]. +//! the [Template_syntax] module. //! A sample template may look like this: //! //! ```html @@ -45,7 +45,6 @@ //! //! [Twirl]: https://github.com/playframework/twirl //! [Play framework]: https://www.playframework.com/ -//! [the _Template syntax_ module]: Template_syntax/index.html //! [examples in the repository]: https://github.com/kaj/ructe/tree/master/examples //! [using ructe with warp and diesel]: https://github.com/kaj/warp-diesel-ructe-sample //! @@ -54,8 +53,6 @@ //! A minimal such build script looks like the following. //! See the [`Ructe`] struct documentation for details. //! -//! [`Ructe`]: struct.Ructe.html -//! //! ```rust,no_run //! use ructe::{Result, Ructe}; //! @@ -89,8 +86,8 @@ //! version 0.3.x of the [mime] crate. //! * `mime02` -- Static files know their mime types, compatible with //! version 0.2.x of the [mime] crate. -//! * `warp03` -- Provide an extension to [`Response::Builder`] to -//! simplify template rendering in the [warp] framework, versions 0.3.x. +//! * `warp03` -- Provide an extension to `Response::Builder` of the [warp] +//! framework (versions 0.3.x) to simplify template rendering. //! * `http-types` -- Static files know their mime types, compatible with //! the [http-types] crate. //! * `tide013`, `tide014`, `tide015`, `tide016` -- Support for the @@ -101,7 +98,6 @@ //! are actually just aliases for the first one, but a future tide //! version may require a modified feature.) //! -//! [`response::Builder`]: ../http/response/struct.Builder.html //! [mime]: https://crates.rs/crates/mime //! [warp]: https://crates.rs/crates/warp //! [tide]: https://crates.rs/crates/tide @@ -218,10 +214,9 @@ impl Ructe { /// `out_dir`. /// /// If you are using Ructe in a project that uses [cargo], - /// you should probably use [`from_env`] instead. + /// you should probably use [`Ructe::from_env`] instead. /// /// [cargo]: https://doc.rust-lang.org/cargo/ - /// [`from_env`]: #method.from_env pub fn new(outdir: PathBuf) -> Result { let mut f = Vec::with_capacity(512); let outdir = outdir.join("templates"); @@ -300,8 +295,7 @@ impl Ructe { /// `templates::statics::logo_png` as a [`StaticFile`] in your /// project. /// - /// [`StaticFiles`]: struct.StaticFiles.html - /// [`StaticFile`]: templates/struct.StaticFile.html + /// [`StaticFile`]: templates::StaticFile pub fn statics(&mut self) -> Result { self.f.write_all(b"pub mod statics;")?; StaticFiles::for_template_dir( @@ -461,6 +455,4 @@ impl From for RucteError { } /// A result where the error type is a [`RucteError`]. -/// -/// [`RucteError`]: enum.RucteError.html pub type Result = std::result::Result; diff --git a/src/templates/utils_warp03.rs b/src/templates/utils_warp03.rs index 07685d2..37a7828 100644 --- a/src/templates/utils_warp03.rs +++ b/src/templates/utils_warp03.rs @@ -1,7 +1,7 @@ use mime::TEXT_HTML_UTF_8; use std::error::Error; use std::io; -use warp::http::{header::CONTENT_TYPE, response::Builder}; +use warp::http::{header::CONTENT_TYPE, response}; use warp::{reject::Reject, reply::Response, Reply}; /// Extension trait for [`response::Builder`] to simplify template rendering. @@ -18,10 +18,12 @@ use warp::{reject::Reject, reply::Response, Reply}; /// /// ``` /// # use std::io::{self, Write}; -/// # use warp::http::Response; -/// # use ructe::templates::RenderRucte; +/// use warp::http::Response; +/// use ructe::templates::RenderRucte; +/// /// # fn page(o: &mut Write, _: u8, _: u8) -> io::Result<()> { Ok(()) } /// # let (title, body) = (47, 11); +/// // ... at the end of a handler: /// Response::builder().html(|o| page(o, title, body)) /// # ; /// ``` @@ -41,7 +43,8 @@ use warp::{reject::Reject, reply::Response, Reply}; /// # ; /// ``` /// -/// [`response::Builder`]: ../../http/response/struct.Builder.html +/// Note that the `.html` method _finalizes_ the builder, that is, on +/// success it returns a [`Response`] rather than a [`response::Builder`]. pub trait RenderRucte { /// Render a template on the response builder. /// @@ -51,7 +54,7 @@ pub trait RenderRucte { F: FnOnce(&mut Vec) -> io::Result<()>; } -impl RenderRucte for Builder { +impl RenderRucte for response::Builder { fn html(self, f: F) -> Result where F: FnOnce(&mut Vec) -> io::Result<()>,