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).

Author: aDotInTheVoid

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
                 );
             }

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)
                 }),
             );
         }

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<P: AsRef<Path>>(
+pub(crate) fn render_and_write<P: AsRef<Path>>(
     input: P,
     options: RenderOptions,
     edition: Edition,