Turn Markdown headers into named anchors that link to themselves

We formed md4c to add the functionality into the parser, so point the
git submodule to that fork. The md4c project seems to be unmaintained
which is why we did it that way. mity/md4c#192

Then move markdown parsing to the generate step so that we can track
repeated self links per-page and increment a counter on each one to
make them unique.

Add missing Result::and_then() to support this use of Result. It still
needs tests (and the Copy overload).

Author: danakj

.gitmodules

@@ -12,4 +12,4 @@
 	url = https://github.com/martinus/nanobench
 [submodule "third_party/md4c"]
 	path = third_party/md4c
-	url = https://github.com/mity/md4c
+	url = https://github.com/danakj/md4c

subdoc/lib/database.h

@@ -19,6 +19,7 @@
 #include "subdoc/lib/doc_attributes.h"
 #include "subdoc/lib/friendly_names.h"
 #include "subdoc/lib/method_qualifier.h"
+#include "subdoc/lib/parse_comment.h"
 #include "subdoc/lib/path.h"
 #include "subdoc/lib/record_type.h"
 #include "subdoc/lib/requires.h"
@@ -35,30 +36,33 @@ namespace subdoc {
 
 struct Comment {
   Comment() = default;
-  Comment(std::string full_html, std::string summary_html,
-          std::string begin_loc, DocAttributes attrs)
-      : full_html(sus::move(full_html)),
-        summary_html(sus::move(summary_html)),
+  Comment(std::string text, std::string begin_loc, DocAttributes attrs)
+      : text(sus::move(text)),
         begin_loc(sus::move(begin_loc)),
         attrs(sus::move(attrs)) {}
 
-  std::string full_html;
-  std::string summary_html;
+  std::string text;
   std::string begin_loc;
   DocAttributes attrs;
 
   void inherit_from(const Comment& source) {
-    full_html = sus::clone(source.full_html);
-    summary_html = sus::clone(source.summary_html);
+    text = sus::clone(source.text);
     attrs = sus::clone(source.attrs);
     // location is not modified.
   }
 
-  std::string_view summary() const& { return summary_html; }
-  std::string_view summary() && = delete;
-
-  std::string_view full() const& { return full_html; }
-  std::string_view full() && = delete;
+  sus::Result<std::string, ParseCommentError> parsed_full(
+      ParseMarkdownPageState& page_state) const noexcept {
+    return parse_comment_markdown_to_html(text, page_state);
+  }
+  sus::Result<std::string, ParseCommentError> parsed_summary(
+      ParseMarkdownPageState& page_state) const noexcept {
+    return parse_comment_markdown_to_html(text, page_state)
+        .and_then(
+            [](std::string s) -> sus::Result<std::string, ParseCommentError> {
+              return sus::ok(summarize_html(sus::move(s)));
+            });
+  }
 };
 
 struct CommentElement {
@@ -78,7 +82,7 @@ struct CommentElement {
   u32 sort_key;
 
   bool has_comment() const {
-    return !comment.full_html.empty() || comment.attrs.inherit.is_some() ||
+    return !comment.text.empty() || comment.attrs.inherit.is_some() ||
            comment.attrs.hidden;
   }
   bool hidden() const { return comment.attrs.hidden; }

subdoc/lib/gen/generate_function.cc

@@ -23,6 +23,7 @@
 #include "subdoc/lib/gen/generate_requires.h"
 #include "subdoc/lib/gen/html_writer.h"
 #include "subdoc/lib/gen/options.h"
+#include "subdoc/lib/parse_comment.h"
 #include "sus/prelude.h"
 
 namespace subdoc::gen {
@@ -36,26 +37,26 @@ enum Style {
 
 void generate_return_type(HtmlWriter::OpenDiv& div,
                           const FunctionOverload& overload) noexcept {
-  {
+  if (overload.return_type_element.is_some()) {
     auto return_type_link = div.open_a();
     return_type_link.add_class("type-name");
     return_type_link.add_title(overload.return_type_name);
-    if (overload.return_type_element.is_some()) {
-      if (!overload.return_type_element->hidden()) {
-        return_type_link.add_href(
-            construct_html_file_path(
-                std::filesystem::path(),
-                overload.return_type_element->namespace_path.as_slice(),
-                overload.return_type_element->record_path.as_slice(),
-                overload.return_type_element->name)
-                .string());
-      } else {
-        llvm::errs() << "WARNING: Reference to hidden TypeElement "
-                     << overload.return_type_element->name << " in namespace "
-                     << overload.return_type_element->namespace_path;
-      }
+    if (!overload.return_type_element->hidden()) {
+      return_type_link.add_href(
+          construct_html_file_path(
+              std::filesystem::path(),
+              overload.return_type_element->namespace_path.as_slice(),
+              overload.return_type_element->record_path.as_slice(),
+              overload.return_type_element->name)
+              .string());
+    } else {
+      llvm::errs() << "WARNING: Reference to hidden TypeElement "
+                   << overload.return_type_element->name << " in namespace "
+                   << overload.return_type_element->namespace_path;
     }
     return_type_link.write_text(overload.return_short_type_name);
+  } else {
+    div.write_text(overload.return_short_type_name);
   }
 }
 
@@ -66,26 +67,25 @@ void generate_function_params(HtmlWriter::OpenDiv& div,
     for (const auto& [i, p] : overload.parameters.iter().enumerate()) {
       if (i > 0u) div.write_text(", ");
 
-      {
+      if (p.type_element.is_some()) {
         auto one_param_link = div.open_a();
         one_param_link.add_class("type-name");
         one_param_link.add_title(p.type_name);
-        if (p.type_element.is_some()) {
-          if (!p.type_element->hidden()) {
-            one_param_link.add_href(
-                construct_html_file_path(
-                    std::filesystem::path(),
-                    p.type_element->namespace_path.as_slice(),
-                    p.type_element->record_path.as_slice(),
-                    p.type_element->name)
-                    .string());
-          } else {
-            llvm::errs() << "WARNING: Reference to hidden TypeElement "
-                         << p.type_element->name << " in namespace "
-                         << p.type_element->namespace_path;
-          }
+        if (!p.type_element->hidden()) {
+          one_param_link.add_href(construct_html_file_path(
+                                      std::filesystem::path(),
+                                      p.type_element->namespace_path.as_slice(),
+                                      p.type_element->record_path.as_slice(),
+                                      p.type_element->name)
+                                      .string());
+        } else {
+          llvm::errs() << "WARNING: Reference to hidden TypeElement "
+                       << p.type_element->name << " in namespace "
+                       << p.type_element->namespace_path;
         }
         one_param_link.write_text(p.short_type_name);
+      } else {
+        div.write_text(p.short_type_name);
       }
 
       if (!p.parameter_name.empty()) {
@@ -221,6 +221,8 @@ void generate_function(const FunctionElement& element,
                        u32 overload_set, const Options& options) noexcept {
   if (element.hidden()) return;
 
+  ParseMarkdownPageState page_state;
+
   const std::filesystem::path path = construct_html_file_path_for_function(
       options.output_root, element, overload_set);
   std::filesystem::create_directories(path.parent_path());
@@ -331,13 +333,14 @@ void generate_function(const FunctionElement& element,
     auto desc_div = section_div.open_div();
     desc_div.add_class("description");
     desc_div.add_class("long");
-    desc_div.write_html(element.comment.full());
+    desc_div.write_html(element.comment.parsed_full(page_state).unwrap());
   }
 }
 
 void generate_function_reference(HtmlWriter::OpenUl& items_list,
                                  const FunctionElement& element,
-                                 u32 overload_set) noexcept {
+                                 u32 overload_set,
+                                 ParseMarkdownPageState& page_state) noexcept {
   auto item_li = items_list.open_li();
   item_li.add_class("section-item");
 
@@ -356,13 +359,14 @@ void generate_function_reference(HtmlWriter::OpenUl& items_list,
     auto desc_div = item_li.open_div();
     desc_div.add_class("description");
     desc_div.add_class("short");
-    if (element.has_comment()) desc_div.write_html(element.comment.summary());
+    if (element.has_comment())
+      desc_div.write_html(element.comment.parsed_summary(page_state).unwrap());
   }
 }
 
-void generate_function_long_reference(HtmlWriter::OpenDiv& item_div,
-                                      const FunctionElement& element,
-                                      u32 overload_set) noexcept {
+void generate_function_long_reference(
+    HtmlWriter::OpenDiv& item_div, const FunctionElement& element,
+    u32 overload_set, ParseMarkdownPageState& page_state) noexcept {
   {
     auto overload_set_div = item_div.open_div();
     overload_set_div.add_class("overload-set");
@@ -374,7 +378,8 @@ void generate_function_long_reference(HtmlWriter::OpenDiv& item_div,
     auto desc_div = item_div.open_div();
     desc_div.add_class("description");
     desc_div.add_class("long");
-    if (element.has_comment()) desc_div.write_html(element.comment.full());
+    if (element.has_comment())
+      desc_div.write_html(element.comment.parsed_full(page_state).unwrap());
   }
 }
 

subdoc/lib/gen/generate_function.h

@@ -17,6 +17,7 @@
 #include "subdoc/lib/database.h"
 #include "subdoc/lib/gen/html_writer.h"
 #include "subdoc/lib/gen/options.h"
+#include "subdoc/lib/parse_comment.h"
 
 namespace subdoc::gen {
 
@@ -25,11 +26,11 @@ void generate_function(const FunctionElement& e,
                        u32 overload_set, const Options& options) noexcept;
 
 void generate_function_reference(HtmlWriter::OpenUl& items_list,
-                                 const FunctionElement& e,
-                                 u32 overload_set) noexcept;
+                                 const FunctionElement& e, u32 overload_set,
+                                 ParseMarkdownPageState& page_state) noexcept;
 
-void generate_function_long_reference(HtmlWriter::OpenDiv& items_list,
-                                      const FunctionElement& e,
-                                      u32 overload_set) noexcept;
+void generate_function_long_reference(
+    HtmlWriter::OpenDiv& items_list, const FunctionElement& e, u32 overload_set,
+    ParseMarkdownPageState& page_state) noexcept;
 
 }  // namespace subdoc::gen