allow for hackily specifying external libraries that should be documented

matcool · matcool · commit 9a62d9472f61 · 2025-02-23T01:07:33.000-03:00
diff --git a/src/builder/builder.rs b/src/builder/builder.rs
@@ -33,7 +33,7 @@ impl<'e> Builder<'e> {
     ) -> Result<Self, String> {
         Self {
             config: config.clone(),
-            root: Namespace::new_root(root),
+            root: Namespace::new_root(root, config.clone()),
             _clang: clang,
             index,
             args,
diff --git a/src/builder/namespace.rs b/src/builder/namespace.rs
@@ -1,15 +1,15 @@
-use std::collections::HashMap;
+use std::{collections::HashMap, sync::Arc};
 
 use clang::{Entity, EntityKind};
 
-use crate::url::UrlPath;
+use crate::{config::Config, url::UrlPath};
 
 use super::{
-    traits::{ASTEntry, BuildResult, EntityMethods, Entry, NavItem},
     builder::Builder,
     class::Class,
     function::Function,
     struct_::Struct,
+    traits::{ASTEntry, BuildResult, EntityMethods, Entry, NavItem},
 };
 
 pub enum CppItemKind {
@@ -23,7 +23,9 @@ impl CppItemKind {
     pub fn from(entity: &Entity) -> Option<Self> {
         match entity.get_kind() {
             EntityKind::StructDecl => Some(Self::Struct),
-            EntityKind::ClassDecl | EntityKind::ClassTemplate | EntityKind::ClassTemplatePartialSpecialization => Some(Self::Class),
+            EntityKind::ClassDecl
+            | EntityKind::ClassTemplate
+            | EntityKind::ClassTemplatePartialSpecialization => Some(Self::Class),
             EntityKind::FunctionDecl | EntityKind::FunctionTemplate => Some(Self::Function),
             EntityKind::Namespace => Some(Self::Namespace),
             _ => None,
@@ -48,7 +50,11 @@ pub enum CppItem<'e> {
 }
 
 impl<'e> CppItem<'e> {
-    fn get(&'e self, matcher: &dyn Fn(&dyn ASTEntry<'e>) -> bool, out: &mut Vec<&'e dyn ASTEntry<'e>>) {
+    fn get(
+        &'e self,
+        matcher: &dyn Fn(&dyn ASTEntry<'e>) -> bool,
+        out: &mut Vec<&'e dyn ASTEntry<'e>>,
+    ) {
         match self {
             CppItem::Namespace(ns) => {
                 if matcher(ns) {
@@ -57,22 +63,22 @@ impl<'e> CppItem<'e> {
                 for entry in ns.entries.values() {
                     entry.get(&matcher, out);
                 }
-            },
+            }
             CppItem::Class(cls) => {
                 if matcher(cls) {
                     out.push(cls);
                 }
-            },
+            }
             CppItem::Struct(cls) => {
                 if matcher(cls) {
                     out.push(cls);
                 }
-            },
+            }
             CppItem::Function(fun) => {
                 if matcher(fun) {
                     out.push(fun);
                 }
-            },
+            }
         }
     }
 }
@@ -142,35 +148,50 @@ pub struct Namespace<'e> {
 }
 
 impl<'e> Namespace<'e> {
-    pub fn new(entity: Entity<'e>) -> Self {
+    pub fn new(entity: Entity<'e>, config: Arc<Config>) -> Self {
         let mut ret = Self {
             entity,
             is_root: false,
             entries: HashMap::new(),
         };
-        ret.load_entries();
+        ret.load_entries(config);
         ret
     }
 
-    pub fn new_root(entity: Entity<'e>) -> Self {
+    pub fn new_root(entity: Entity<'e>, config: Arc<Config>) -> Self {
         let mut ret = Self {
             entity,
             is_root: true,
             entries: HashMap::new(),
         };
-        ret.load_entries();
+        ret.load_entries(config);
         ret
     }
 
-    fn load_entries(&mut self) {
+    fn load_entries(&mut self, config: Arc<Config>) {
         for child in &self.entity.get_children() {
-            if child.is_in_system_header() || child.get_name().is_none() {
+            // skip unnamed items
+            if child.get_name().is_none() {
                 continue;
             }
+
+            // skip stuff from external headers
+            if child.is_in_system_header() && child.get_allowed_external_lib(config.clone()).is_none() {
+                continue;
+            }
+
+            // skips specialization of std stuff
+            let is_parent_std = child
+                .get_semantic_parent()
+                .map_or(false, |f| f.get_name().as_deref() == Some("std"));
+            if is_parent_std {
+                continue;
+            }
+
             if let Some(kind) = CppItemKind::from(child) {
                 match kind {
                     CppItemKind::Namespace => {
-                        let entry = Namespace::new(*child);
+                        let entry = Namespace::new(*child, config.clone());
                         // Merge existing entries of namespace
                         if let Some(key) = self.entries.get_mut(&entry.name()) {
                             if let CppItem::Namespace(ns) = key {
@@ -206,7 +227,7 @@ impl<'e> Namespace<'e> {
         }
     }
 
-    // so apparently if you make this a <M: Fn(&dyn ASTEntry<'e>) -> bool> 
+    // so apparently if you make this a <M: Fn(&dyn ASTEntry<'e>) -> bool>
     // rustc crashes
     pub fn get(&'e self, matcher: &dyn Fn(&dyn ASTEntry<'e>) -> bool) -> Vec<&'e dyn ASTEntry<'e>> {
         let mut res = Vec::new();
@@ -252,9 +273,10 @@ impl<'e> Entry<'e> for Namespace<'e> {
     fn url(&self) -> UrlPath {
         if self.is_root {
             UrlPath::new()
-        }
-        else {
-            self.entity.rel_docs_url().expect("Unable to get namespace URL")
+        } else {
+            self.entity
+                .rel_docs_url()
+                .expect("Unable to get namespace URL")
         }
     }
 }
diff --git a/src/builder/shared.rs b/src/builder/shared.rs
@@ -321,11 +321,14 @@ pub fn fmt_section(title: &str, data: Vec<Html>) -> Html {
 }
 
 pub fn fmt_header_link(entity: &Entity, config: Arc<Config>) -> Html {
-    if let Some(link) = entity.github_url(config.clone()) &&
-        let Some(path) = entity.include_path(config.clone()) &&
-        let Some(src) = entity.config_source(config)
+    if let Some(link) = entity.github_url(config.clone())
+        && let Some(path) = entity.include_path(config.clone())
     {
-        let disabled = !src.exists_online;
+        let exists_online = entity
+            .config_source(config.clone())
+            .map(|s| s.exists_online)
+            .unwrap_or(true);
+        let disabled = !exists_online;
         HtmlElement::new("a")
             .with_attr_opt("href", (!disabled).then_some(link))
             .with_class("header-link")
diff --git a/src/builder/traits.rs b/src/builder/traits.rs
@@ -5,7 +5,7 @@ use std::{path::PathBuf, sync::Arc, collections::HashMap};
 use tokio::task::JoinHandle;
 
 use crate::{
-    config::{Config, Source},
+    config::{Config, ExternalLib, Source},
     html::{Html, HtmlElement, HtmlList, HtmlText},
     url::UrlPath,
 };
@@ -52,6 +52,9 @@ pub trait EntityMethods<'e> {
 
     /// Same as extract_source_string, but removes new lines, double spaces, and leading/trailing whitespace
     fn extract_source_string_cleaned(&self) -> Option<String>;
+
+    /// Checks if the entitiy is in one of the allowed external libraries
+    fn get_allowed_external_lib(&self, config: Arc<Config>) -> Option<Arc<ExternalLib>>;
 }
 
 impl<'e> EntityMethods<'e> for Entity<'e> {
@@ -106,13 +109,10 @@ impl<'e> EntityMethods<'e> for Entity<'e> {
     }
 
     fn github_url(&self, config: Arc<Config>) -> Option<String> {
-        // If this is an std item, redirect to cppreference instead
         if self.full_name().first().is_some_and(|n| n == "std") {
-            Some(format!(
-                "https://en.cppreference.com/w/cpp/{}/{}",
-                self.definition_file()?.file_name()?.to_str()?,
-                self.get_name()?
-            ))
+            unreachable!("Shouldn't be trying to link to a stl header - {:?}", self.get_name())
+        } else if let Some(lib) = self.get_allowed_external_lib(config.clone()) {
+            Some(lib.repository.clone())
         } else {
             Some(
                 config.project.tree.clone()?
@@ -122,6 +122,9 @@ impl<'e> EntityMethods<'e> for Entity<'e> {
     }
 
     fn include_path(&self, config: Arc<Config>) -> Option<UrlPath> {
+        if self.is_in_system_header() {
+            return UrlPath::part(self.header(config.clone())?.file_name()?.to_string_lossy().as_ref()).into()
+        }
         UrlPath::try_from(&self.header(config.clone())?)
             .ok()?
             .strip_prefix(&self.config_source(config)?.dir)
@@ -151,6 +154,11 @@ impl<'e> EntityMethods<'e> for Entity<'e> {
                 }
             }
         }
+        // remove leading anon namespaces
+        let mut ancestors: Vec<_> = ancestors
+            .into_iter()
+            .skip_while(|e| e.get_name().is_none())
+            .collect();
         ancestors.push(*self);
         ancestors
     }
@@ -214,6 +222,22 @@ impl<'e> EntityMethods<'e> for Entity<'e> {
             .intersperse(" ")
             .collect())
     }
+
+    fn get_allowed_external_lib(&self, config: Arc<Config>) -> Option<Arc<ExternalLib>> {
+        self.is_in_system_header()
+            .then(|| self.get_location())
+            .flatten()
+            .and_then(|x| x.get_file_location().file)
+            .and_then(|file| {
+                let path = file.get_path();
+                let path = path.to_string_lossy();
+                config
+                    .external_libs
+                    .as_ref()
+                    .and_then(|x| x.iter().find(|f| path.contains(&f.pattern)))
+            })
+            .cloned()
+    }
 }
 
 #[derive(Clone)]
diff --git a/src/config.rs b/src/config.rs
@@ -118,6 +118,11 @@ decl_config! {
         exists_online: bool = true,
     }
 
+    struct ExternalLib {
+        pattern: String,
+        repository: String,
+    }
+
     struct Config {
         project {
             name: String,
@@ -126,6 +131,7 @@ decl_config! {
             tree?: String,
             icon?: PathBuf,
         },
+        external_libs?: Vec<Arc<ExternalLib>>,
         tutorials? {
             dir: PathBuf,
             assets: Vec<PathBuf> as parse_glob = Vec::new(),
