Add documentation for new `FormatRenderer` trait items

2 files changed, 30 insertions, 2 deletions

diff --git a/src/librustdoc/formats/renderer.rs b/src/librustdoc/formats/renderer.rs
index f7ba5bff51b..8ae3cad74e3 100644
--- a/src/librustdoc/formats/renderer.rs
+++ b/src/librustdoc/formats/renderer.rs
@@ -17,6 +17,17 @@ pub(crate) trait FormatRenderer<'tcx>: Sized {
     ///
     /// This is true for html, and false for json. See #80664
     const RUN_ON_MODULE: bool;
+    /// This associated type is the type where the current module information is stored.
+    ///
+    /// For each module, we go through their items by calling for each item:
+    ///
+    /// 1. make_child_renderer
+    /// 2. item
+    /// 3. set_back_info
+    ///
+    /// However,the `item` method might update information in `self` (for example if the child is
+    /// a module). To prevent it to impact the other children of the current module, we need to
+    /// reset the information between each call to `item` by using `set_back_info`.
     type InfoType;
 
     /// Sets up any state required for the renderer. When this is called the cache has already been
@@ -28,9 +39,20 @@ pub(crate) trait FormatRenderer<'tcx>: Sized {
         tcx: TyCtxt<'tcx>,
     ) -> Result<(Self, clean::Crate), Error>;
 
-    /// Make a new renderer to render a child of the item currently being rendered.
+    /// This method is called right before call [`Self::item`]. This method returns a type
+    /// containing information that needs to be reset after the [`Self::item`] method has been
+    /// called with the [`Self::set_back_info`] method.
+    ///
+    /// In short it goes like this:
+    ///
+    /// ```ignore (not valid code)
+    /// let reset_data = type.make_child_renderer();
+    /// type.item(item)?;
+    /// type.set_back_info(reset_data);
+    /// ```
     fn make_child_renderer(&mut self) -> Self::InfoType;
-    fn set_back_info(&mut self, _info: Self::InfoType);
+    /// Used to reset current module's information.
+    fn set_back_info(&mut self, info: Self::InfoType);
 
     /// Renders a single non-module item. This means no recursive sub-item rendering is required.
     fn item(&mut self, item: clean::Item) -> Result<(), Error>;
diff --git a/src/librustdoc/html/render/context.rs b/src/librustdoc/html/render/context.rs
index 81a9cce80d1..c2d0bc915b0 100644
--- a/src/librustdoc/html/render/context.rs
+++ b/src/librustdoc/html/render/context.rs
@@ -66,6 +66,12 @@ pub(crate) struct Context<'tcx> {
     pub(crate) info: ContextInfo,
 }
 
+/// This struct contains the information that needs to be reset between each
+/// [`FormatRenderer::render_item`] call.
+///
+/// When we enter a new module, we set these values for the whole module but they might be updated
+/// in each child item (especially if it's a module). So to prevent these changes to impact other
+/// items rendering in the same module, we need to reset them to the module's set values.
 #[derive(Clone, Copy)]
 pub(crate) struct ContextInfo {
     /// A flag, which when `true`, will render pages which redirect to the