rdmsr · famfo · May 28, 2025 · May 28, 2025 · May 28, 2025 · Jun 3, 2025
diff --git a/CONFIG.md b/CONFIG.md
@@ -14,6 +14,9 @@ The configuration file is a TOML file named `cppdoc.toml` with the following sec
 - `path`: Path to the output directory.
 - `root_namespace` (optional): Namespace to use as the root, this is useful for libraries that only globally expose one namespace and want the index to be based on that namespace.
 - `base_url`: Base URL to prepend all paths with.
+- `enable_mermaid`: Weather to enable mermaid, default: `true`
+- `bundle_mermaid`: Weather to bundle mermaid (`mermaid.mjs` in the static directory), otherwise it is fetched from a release online, default: `false`
+- `bundle_minisearch`: Weather to bundle minisearch (`minisearch.js` in the static directory), otherwise it is fetched from a release online, default `false`
 
 ## `pages`
 - `index` (optional): Markdown file to use as the index file, if an index page is not specified, the root namespace's comment will be used instead.

diff --git a/USAGE.md b/USAGE.md
@@ -23,12 +23,22 @@ Comments are written using `///` or `//<`, the latter being used for inline docu
 ```cpp
 /// Documentation for 'MyEnum'
 enum MyEnum {
-	A //< Documentation for 'A' 
+    ///< Documentation for 'A' 
+	A
 }
 ```
 
 Comments content are parsed as cppdoc-flavored markdown, there is no support for `javadoc`/Doxygen-style comments.
 
+### Hiding nodes
+
+Nodes can be hidden by annotating them with `/// #[doc(hidden)]`
+
+```cpp
+/// #[doc(hidden)]
+struct Hidden {}
+```
+
 ## Markdown syntax
 `cppdoc` introduces a few extensions to markdown.
 

diff --git a/src/comment.rs b/src/comment.rs
@@ -8,25 +8,38 @@ fn remove_prefix_and_clean(string: &str, prefix: &str) -> String {
     }
 }
 
-pub fn parse_comment(string: String) -> Comment {
+pub fn parse_comment(string: String) -> Option<Comment> {
     let mut ret = Comment {
         brief: "".to_string(),
         description: "".to_string(),
         impl_: None,
     };
 
     let mut lines = string.lines();
+    if lines.clone().peekable().peek() == Some(&"/// #[doc(hidden)]") {
+        return None;
+    }
 
-    if let Some(line) = lines.next() {
+    let mut brief = String::new();
+    while let Some(line) = lines.next() {
         let trimmed = line.trim();
+        if trimmed.is_empty() {
+            break;
+        }
+
+        if !brief.is_empty() {
+            brief.push(' ');
+        }
 
         if trimmed.starts_with("///<") {
-            ret.brief = remove_prefix_and_clean(trimmed, "///<");
+            brief.push_str(&remove_prefix_and_clean(trimmed, "///<"));
         } else {
-            ret.brief = remove_prefix_and_clean(trimmed, "///");
+            brief.push_str(&remove_prefix_and_clean(trimmed, "///"));
         }
     }
 
+    ret.brief = brief;
+
     let description = lines.fold(String::new(), |mut acc, line| {
         let cleaned_up = remove_prefix_and_clean(line.trim(), "///");
 
@@ -48,5 +61,5 @@ pub fn parse_comment(string: String) -> Comment {
 
     ret.description = description.trim().to_string();
 
-    ret
+    Some(ret)
 }
diff --git a/src/config.rs b/src/config.rs
@@ -34,6 +34,16 @@ pub struct Output {
     pub path: String,
     pub root_namespace: Option<String>,
     pub base_url: String,
+    #[serde(default = "bool_true")]
+    pub enable_mermaid: bool,
+    #[serde(default)]
+    pub bundle_mermaid: bool,
+    #[serde(default)]
+    pub bundle_minisearch: bool,
+}
+
+fn bool_true() -> bool {
+    true
 }
 
 #[derive(Deserialize, Serialize, Clone, Debug)]

diff --git a/src/parser.rs b/src/parser.rs
@@ -151,7 +151,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    fn parse_function(&self, node: clang::Entity) -> Function {
+    fn parse_function(&self, node: clang::Entity) -> Option<Function> {
         let mut ret = Function {
             name: node.get_name().unwrap(),
             return_type: node.get_result_type().unwrap().get_display_name(),
@@ -170,7 +170,12 @@ impl<'a> Parser<'a> {
         // Handle function names with quotes, like operator"", so that links don't fuck up
         ret.name = ret.name.replace("\"", "&quot");
 
-        if let Some(c) = node.get_comment() { ret.comment = Some(comment::parse_comment(c)); }
+        if let Some(c) = node.get_comment() {
+            ret.comment = comment::parse_comment(c);
+            if ret.comment.is_none() {
+                return None;
+            }   
+        }
 
         for c in node
             .get_children()
@@ -190,10 +195,10 @@ impl<'a> Parser<'a> {
             ret.template = Some(self.parse_template(node));
         }
 
-        ret
+        Some(ret)
     }
 
-    fn parse_record(&self, node: clang::Entity) -> Record {
+    fn parse_record(&self, node: clang::Entity) -> Option<Record> {
         let mut ret = Record {
             name: node.get_name().unwrap(),
             fields: Vec::new(),
@@ -215,7 +220,12 @@ impl<'a> Parser<'a> {
             nested: None,
         };
 
-        if let Some(c) = node.get_comment() { ret.comment = Some(comment::parse_comment(c)); }
+        if let Some(c) = node.get_comment() {
+            ret.comment = comment::parse_comment(c);
+            if ret.comment.is_none() {
+                return None;
+            }   
+        }
 
         if node.get_kind() == clang::EntityKind::ClassTemplate {
             ret.template = Some(self.parse_template(node));
@@ -224,10 +234,16 @@ impl<'a> Parser<'a> {
         for c in node.get_children().iter() {
             match c.get_kind() {
                 clang::EntityKind::FieldDecl => if let Some(clang::Accessibility::Public) = c.get_accessibility() {
+                    let comment = if let Some(comment) = node.get_comment() {
+                        comment::parse_comment(comment)
+                    } else {
+                        None
+                    };
+
                     let mut field = Field {
                         name: c.get_name().unwrap_or_default(),
                         type_: c.get_type().unwrap().get_display_name(),
-                        comment: c.get_comment().map(comment::parse_comment),
+                        comment,
                         struct_: None,
                     };
 
@@ -238,7 +254,7 @@ impl<'a> Parser<'a> {
                                 .iter()
                                 .find(|c| c.get_kind() == clang::EntityKind::StructDecl)
                                 .unwrap(),
-                        );
+                        )?;
 
                         field.type_ = "struct".to_string();
                         field.struct_ = Some(NestedField::Record(ret_struct));
@@ -250,7 +266,7 @@ impl<'a> Parser<'a> {
                                 .iter()
                                 .find(|c| c.get_kind() == clang::EntityKind::UnionDecl)
                                 .unwrap(),
-                        );
+                        )?;
 
                         field.type_ = "union".to_string();
                         field.struct_ = Some(NestedField::Record(ret_struct));
@@ -262,7 +278,7 @@ impl<'a> Parser<'a> {
                                 .iter()
                                 .find(|c| c.get_kind() == clang::EntityKind::EnumDecl)
                                 .unwrap(),
-                        );
+                        )?;
 
                         field.type_ = "enum".to_string();
                         field.struct_ = Some(NestedField::Enum(ret_enum));
@@ -272,15 +288,15 @@ impl<'a> Parser<'a> {
                 },
 
                 clang::EntityKind::Constructor => {
-                    let mut function = self.parse_function(*c);
+                    let mut function = self.parse_function(*c)?;
                     function.return_type = "".to_string();
 
                     ret.ctor.push(function);
                 }
 
                 clang::EntityKind::Method | clang::EntityKind::FunctionTemplate => {
                     if let Some(clang::Accessibility::Public) = c.get_accessibility() {
-                        let mut function = self.parse_function(*c);
+                        let mut function = self.parse_function(*c)?;
                         function.namespace = Some(ret.name.clone());
 
                         ret.methods.push(function);
@@ -291,7 +307,7 @@ impl<'a> Parser<'a> {
                 | clang::EntityKind::ClassDecl
                 | clang::EntityKind::UnionDecl
                 | clang::EntityKind::ClassTemplate => {
-                    let mut record = self.parse_record(*c);
+                    let mut record = self.parse_record(*c)?;
 
                     if !record.name.starts_with("(anonymous")
                         && !record.name.starts_with("(unnamed")
@@ -307,7 +323,7 @@ impl<'a> Parser<'a> {
                 }
 
                 clang::EntityKind::EnumDecl => {
-                    let mut enum_ = self.parse_enum(*c);
+                    let mut enum_ = self.parse_enum(*c)?;
 
                     if !enum_.name.starts_with("(anonymous") && !enum_.name.starts_with("(unnamed")
                     {
@@ -327,31 +343,42 @@ impl<'a> Parser<'a> {
             }
         }
 
-        ret
+        Some(ret)
     }
 
-    fn parse_enum(&self, node: clang::Entity) -> Enum {
+    fn parse_enum(&self, node: clang::Entity) -> Option<Enum> {
         let mut ret = Enum {
             name: node.get_name().unwrap(),
             comment: None,
             namespace: None,
             values: Vec::new(),
         };
 
-        if let Some(c) = node.get_comment() { ret.comment = Some(comment::parse_comment(c)); }
+        if let Some(c) = node.get_comment() {
+            ret.comment = comment::parse_comment(c);
+            if ret.comment.is_none() {
+                return None;
+            }   
+        }
 
         for c in node.get_children().iter() {
             if c.get_kind() == clang::EntityKind::EnumConstantDecl {
+                let comment = if let Some(comment) = node.get_comment() {
+                    comment::parse_comment(comment)
+                } else {
+                    None
+                };
+
                 let value = EnumValue {
                     name: c.get_name().unwrap_or_default(),
-                    comment: c.get_comment().map(comment::parse_comment),
+                    comment,
                 };
 
                 ret.values.push(value);
             }
         }
 
-        ret
+        Some(ret)
     }
 
     fn get_name_for_namespace(name: &str, namespace_name: &str, ns_name_full: &str) -> String {
@@ -381,7 +408,10 @@ impl<'a> Parser<'a> {
 
         match node.get_kind() {
             clang::EntityKind::FunctionDecl | clang::EntityKind::FunctionTemplate => {
-                let mut function = self.parse_function(node);
+                let Some(mut function) = self.parse_function(node) else {
+                    return;
+                };
+
                 function.namespace = Some(current_namespace_name.to_string());
 
                 if let Some(existing) = ns.functions.iter_mut().find(|f| f.name == function.name) {
@@ -406,7 +436,10 @@ impl<'a> Parser<'a> {
             | clang::EntityKind::ClassDecl
             | clang::EntityKind::UnionDecl
             | clang::EntityKind::ClassTemplate => {
-                let mut record = self.parse_record(node);
+                let Some(mut record) = self.parse_record(node) else {
+                    return;
+                };
+
                 record.namespace = Some(current_namespace_name.to_string());
 
                 // If a record already exists, it must be some kind of template specialization/overloading,
@@ -464,7 +497,10 @@ impl<'a> Parser<'a> {
             }
 
             clang::EntityKind::EnumDecl => {
-                let mut enum_ = self.parse_enum(node);
+                let Some(mut enum_) = self.parse_enum(node) else {
+                    return;
+                };
+
                 enum_.namespace = Some(current_namespace_name.to_string());
 
                 index.insert(absolute_name, "enum".to_string());
@@ -473,9 +509,15 @@ impl<'a> Parser<'a> {
 
             clang::EntityKind::Namespace => {
                 let name = node.get_name().unwrap();
+                let comment = if let Some(comment) = node.get_comment() {
+                    comment::parse_comment(comment)
+                } else {
+                    None
+                };
+
                 let mut real_ns = Namespace {
                     name: node.get_name().unwrap(),
-                    comment: node.get_comment().map(comment::parse_comment),
+                    comment,
                     records: Vec::new(),
                     functions: Vec::new(),
                     namespaces: Vec::new(),
@@ -549,11 +591,17 @@ impl<'a> Parser<'a> {
                     type_ = "unknown".to_string();
                 }
 
+                let comment = if let Some(comment) = node.get_comment() {
+                    comment::parse_comment(comment)
+                } else {
+                    None
+                };
+
                 let alias = Alias {
                     namespace: Some(current_namespace_name.to_string()),
                     name: node.get_name().unwrap(),
                     type_,
-                    comment: node.get_comment().map(comment::parse_comment),
+                    comment,
                 };
 
                 index.insert(absolute_name, "alias".to_string());

diff --git a/src/templates/page.html b/src/templates/page.html
@@ -8,9 +8,15 @@
 	<meta name="viewport" content="width=device-width, initial-scale=1">
 	<link rel="stylesheet" href="{{ config.output.base_url }}/style.css" />
 	<title>{% block title %}{% endblock title %}</title>
+    {% if config.output.enable_mermaid %}
 	<script type="module">
-	  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+        {% if config.output.bundle_mermaid %}
+        import mermaid from '{{ config.output.base_url }}/mermaid.mjs';
+        {% else %}
+        import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+        {% endif %}
 	</script>
+    {% endif %}
 	{% endblock head %}
 
 </head>

diff --git a/src/templates/search.html b/src/templates/search.html
@@ -4,7 +4,11 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <link rel="stylesheet" href="{{ config.output.base_url }}/style.css" />
 <title>Search - {{ project.name }} </title>
+{% if config.output.bundle_minisearch %}
+<script src="{{ config.output.base_url }}/minisearch.js"></script>
+{% else %}
 <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/index.min.js"></script>
+{% endif %}
 <script type="text/javascript">
 	// Read file /search_index.json
 	var url = window.location;