chore: Improve code comments

src/mkdocstrings/extension.py

@@ -129,9 +129,14 @@ def run(self, parent: Element, blocks: MutableSequence[str]) -> None:
             el = Element("div", {"class": "mkdocstrings"})
             # The final HTML is inserted as opaque to subsequent processing, and only revealed at the end.
             el.text = self.md.htmlStash.store(html)
-            # So we need to duplicate the headings directly (and delete later), just so 'toc' can pick them up.
+            # We need to duplicate the headings directly, just so 'toc' can pick them up,
+            # otherwise they wouldn't appear in the final table of contents.
+            # These headings are generated by the `BaseHandler.do_heading` method (Jinja filter),
+            # which runs in the inner Markdown conversion layer, and not in the outer one where we are now.
             headings = handler.get_headings()
             el.extend(headings)
+            # These duplicated headings will later be removed by our `_HeadingsPostProcessor` processor,
+            # which runs right after 'toc' (see `MkdocstringsExtension.extendMarkdown`).
 
             page = self._autorefs.current_page
             if page is not None:

src/mkdocstrings/handlers/base.py

@@ -304,7 +304,16 @@ def do_heading(
         Returns:
             An HTML string.
         """
-        # First, produce the "fake" heading, for ToC only.
+        # Produce a heading element that will be used later, in `AutoDocProcessor.run`, to:
+        # - register it in the ToC: right now we're in the inner Markdown conversion layer,
+        #   so we have to bubble up the information to the outer Markdown conversion layer,
+        #   for the ToC extension to pick it up.
+        # - register it in autorefs: right now we don't know what page is being rendered,
+        #   so we bubble up the information again to where autorefs knows the page,
+        #   and can correctly register the heading anchor (id) to its full URL.
+        # - register it in the objects inventory: same as for autorefs,
+        #   we don't know the page here, or the handler (and its domain),
+        #   so we bubble up the information to where the mkdocstrings extension knows that.
         el = Element(f"h{heading_level}", attributes)
         if toc_label is None:
             toc_label = content.unescape() if isinstance(content, Markup) else content
@@ -320,7 +329,7 @@ def do_heading(
         # Start with a heading that has just attributes (no text), and add a placeholder into it.
         el = Element(f"h{heading_level}", attributes)
         el.append(Element("mkdocstrings-placeholder"))
-        # Tell the 'toc' extension to make its additions if configured so.
+        # Tell the inner 'toc' extension to make its additions if configured so.
         toc = cast(TocTreeprocessor, self._md.treeprocessors["toc"])
         if toc.use_anchors:
             toc.add_anchor(el, attributes["id"])