From 3b789565a19b77fd414f304f24ec21d6e1042000 Mon Sep 17 00:00:00 2001 From: Alona Enraght-Moony Date: Sat, 19 Oct 2024 13:37:40 +0000 Subject: [PATCH] rustdoc: Document `markdown` module. Rustdoc markdown handling is currently split between: - html::markdown, which contains all the meaty login - markdown, which is only used for when rustdoc renders a standalone markdown file Adds module-level doc-comment to markdown, and rename the function so it's clear that it's doing IO (instead of just rendering to a string). --- src/librustdoc/html/render/write_shared.rs | 2 +- src/librustdoc/lib.rs | 2 +- src/librustdoc/markdown.rs | 12 +++++++++++- 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/src/librustdoc/html/render/write_shared.rs b/src/librustdoc/html/render/write_shared.rs index 12b6346005697..c82f7e9aaf927 100644 --- a/src/librustdoc/html/render/write_shared.rs +++ b/src/librustdoc/html/render/write_shared.rs @@ -112,7 +112,7 @@ pub(crate) fn write_shared( md_opts.output = cx.dst.clone(); md_opts.external_html = cx.shared.layout.external_html.clone(); try_err!( - crate::markdown::render(&index_page, md_opts, cx.shared.edition()), + crate::markdown::render_and_write(&index_page, md_opts, cx.shared.edition()), &index_page ); } diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 10fc0ea999015..cb9b3985bf67f 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -817,7 +817,7 @@ fn main_args( return wrap_return( dcx, interface::run_compiler(config, |_compiler| { - markdown::render(&md_input, render_options, edition) + markdown::render_and_write(&md_input, render_options, edition) }), ); } diff --git a/src/librustdoc/markdown.rs b/src/librustdoc/markdown.rs index 978f96f38bedf..76eac084907d7 100644 --- a/src/librustdoc/markdown.rs +++ b/src/librustdoc/markdown.rs @@ -1,3 +1,13 @@ +//! Standalone markdown rendering. +//! +//! For the (much more common) case of rendering markdown in doc-comments, see +//! [crate::html::markdown]. +//! +//! This is used when [rendering a markdown file to an html file][docs], without processing +//! rust source code. +//! +//! [docs]: https://doc.rust-lang.org/stable/rustdoc/#using-standalone-markdown-files + use std::fmt::Write as _; use std::fs::{File, create_dir_all, read_to_string}; use std::io::prelude::*; @@ -33,7 +43,7 @@ fn extract_leading_metadata(s: &str) -> (Vec<&str>, &str) { /// (e.g., output = "bar" => "bar/foo.html"). /// /// Requires session globals to be available, for symbol interning. -pub(crate) fn render>( +pub(crate) fn render_and_write>( input: P, options: RenderOptions, edition: Edition,