From e9b0be7090fcb9efaa163161324caf7eced5c716 Mon Sep 17 00:00:00 2001 From: pierwill Date: Sun, 10 Jan 2021 14:51:30 -0800 Subject: [PATCH] Add intra-docs links to docs Also fixes some punctuation and changes some wording. --- src/book/book.rs | 12 +++++------- src/book/init.rs | 2 +- src/book/mod.rs | 18 +++++++++--------- src/config.rs | 2 +- src/lib.rs | 4 ++-- src/renderer/mod.rs | 7 ++----- 6 files changed, 20 insertions(+), 25 deletions(-) diff --git a/src/book/book.rs b/src/book/book.rs index 38d14682..c47ed632 100644 --- a/src/book/book.rs +++ b/src/book/book.rs @@ -66,7 +66,7 @@ fn create_missing(src_dir: &Path, summary: &Summary) -> Result<()> { /// A dumb tree structure representing a book. /// -/// For the moment a book is just a collection of `BookItems` which are +/// For the moment a book is just a collection of [`BookItems`] which are /// accessible by either iterating (immutably) over the book with [`iter()`], or /// recursively applying a closure to each section to mutate the chapters, using /// [`for_each_mut()`]. @@ -160,7 +160,7 @@ pub struct Chapter { pub sub_items: Vec, /// The chapter's location, relative to the `SUMMARY.md` file. pub path: Option, - /// An ordered list of the names of each chapter above this one, in the hierarchy. + /// An ordered list of the names of each chapter above this one in the hierarchy. pub parent_names: Vec, } @@ -181,8 +181,8 @@ impl Chapter { } } - /// Create a new draft chapter that is not attached to a source markdown file and has - /// thus no content. + /// Create a new draft chapter that is not attached to a source markdown file (and thus + /// has no content. pub fn new_draft(name: &str, parent_names: Vec) -> Self { Chapter { name: name.to_string(), @@ -193,7 +193,7 @@ impl Chapter { } } - /// Check if the chapter is a draft chapter, meaning it has no path to a source markdown file + /// Check if the chapter is a draft chapter, meaning it has no path to a source markdown file. pub fn is_draft_chapter(&self) -> bool { match self.path { Some(_) => false, @@ -302,8 +302,6 @@ fn load_chapter>( /// /// This struct shouldn't be created directly, instead prefer the /// [`Book::iter()`] method. -/// -/// [`Book::iter()`]: struct.Book.html#method.iter pub struct BookItems<'a> { items: VecDeque<&'a BookItem>, } diff --git a/src/book/init.rs b/src/book/init.rs index a1043c7f..264c113d 100644 --- a/src/book/init.rs +++ b/src/book/init.rs @@ -28,7 +28,7 @@ impl BookBuilder { } } - /// Set the `Config` to be used. + /// Set the [`Config`] to be used. pub fn with_config(&mut self, cfg: Config) -> &mut BookBuilder { self.config = cfg; self diff --git a/src/book/mod.rs b/src/book/mod.rs index 0723578f..161ffc01 100644 --- a/src/book/mod.rs +++ b/src/book/mod.rs @@ -40,7 +40,7 @@ pub struct MDBook { pub book: Book, renderers: Vec>, - /// List of pre-processors to be run on the book + /// List of pre-processors to be run on the book. preprocessors: Vec>, } @@ -78,7 +78,7 @@ impl MDBook { MDBook::load_with_config(book_root, config) } - /// Load a book from its root directory using a custom config. + /// Load a book from its root directory using a custom `Config`. pub fn load_with_config>(book_root: P, config: Config) -> Result { let root = book_root.into(); @@ -97,7 +97,7 @@ impl MDBook { }) } - /// Load a book from its root directory using a custom config and a custom summary. + /// Load a book from its root directory using a custom `Config` and a custom summary. pub fn load_with_config_and_summary>( book_root: P, config: Config, @@ -121,7 +121,7 @@ impl MDBook { } /// Returns a flat depth-first iterator over the elements of the book, - /// it returns an [BookItem enum](bookitem.html): + /// it returns a [`BookItem`] enum: /// `(section: String, bookitem: &BookItem)` /// /// ```no_run @@ -180,7 +180,7 @@ impl MDBook { Ok(()) } - /// Run the entire build process for a particular `Renderer`. + /// Run the entire build process for a particular [`Renderer`]. pub fn execute_build_process(&self, renderer: &dyn Renderer) -> Result<()> { let mut preprocessed_book = self.book.clone(); let preprocess_ctx = PreprocessorContext::new( @@ -219,14 +219,14 @@ impl MDBook { } /// You can change the default renderer to another one by using this method. - /// The only requirement is for your renderer to implement the [`Renderer` - /// trait](../renderer/trait.Renderer.html) + /// The only requirement is that your renderer implement the [`Renderer`] + /// trait. pub fn with_renderer(&mut self, renderer: R) -> &mut Self { self.renderers.push(Box::new(renderer)); self } - /// Register a [`Preprocessor`](../preprocess/trait.Preprocessor.html) to be used when rendering the book. + /// Register a [`Preprocessor`] to be used when rendering the book. pub fn with_preprocessor(&mut self, preprocessor: P) -> &mut Self { self.preprocessors.push(Box::new(preprocessor)); self @@ -303,7 +303,7 @@ impl MDBook { /// artefacts. /// /// If there is only 1 renderer, put it in the directory pointed to by the - /// `build.build_dir` key in `Config`. If there is more than one then the + /// `build.build_dir` key in [`Config`]. If there is more than one then the /// renderer gets its own directory within the main build dir. /// /// i.e. If there were only one renderer (in this case, the HTML renderer): diff --git a/src/config.rs b/src/config.rs index 14a13ce3..be7dae62 100644 --- a/src/config.rs +++ b/src/config.rs @@ -2,7 +2,7 @@ //! //! The main entrypoint of the `config` module is the `Config` struct. This acts //! essentially as a bag of configuration information, with a couple -//! pre-determined tables (`BookConfig` and `BuildConfig`) as well as support +//! pre-determined tables ([`BookConfig`] and [`BuildConfig`]) as well as support //! for arbitrary data which is exposed to plugins and alternative backends. //! //! diff --git a/src/lib.rs b/src/lib.rs index ff52d211..82d9b6f7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -76,9 +76,9 @@ //! access to the various methods for working with the [`Config`]. //! //! [user guide]: https://rust-lang.github.io/mdBook/ -//! [`RenderContext`]: renderer/struct.RenderContext.html +//! [`RenderContext`]: renderer::RenderContext //! [relevant chapter]: https://rust-lang.github.io/mdBook/for_developers/backends.html -//! [`Config`]: config/struct.Config.html +//! [`Config`]: config::Config #![deny(missing_docs)] #![deny(rust_2018_idioms)] diff --git a/src/renderer/mod.rs b/src/renderer/mod.rs index f14a9f30..2650a2e0 100644 --- a/src/renderer/mod.rs +++ b/src/renderer/mod.rs @@ -34,12 +34,9 @@ use toml::Value; /// provide your own renderer, there are two main renderer implementations that /// 99% of users will ever use: /// -/// - [HtmlHandlebars] - the built-in HTML renderer -/// - [CmdRenderer] - a generic renderer which shells out to a program to do the +/// - [`HtmlHandlebars`] - the built-in HTML renderer +/// - [`CmdRenderer`] - a generic renderer which shells out to a program to do the /// actual rendering -/// -/// [HtmlHandlebars]: struct.HtmlHandlebars.html -/// [CmdRenderer]: struct.CmdRenderer.html pub trait Renderer { /// The `Renderer`'s name. fn name(&self) -> &str;