Implement Documentation

Author: lionel-

crates/ark/src/lsp/diagnostics.rs

@@ -1657,11 +1657,7 @@ foo
                 depends: vec![],
                 fields: Dcf::new(),
             };
-            let package = Package {
-                path: PathBuf::from("/mock/path"),
-                description,
-                namespace,
-            };
+            let package = Package::new(PathBuf::from("/mock/path"), description, namespace);
 
             // Create a library with `mockpkg` installed
             let library = Library::new(vec![]).insert("mockpkg", package);
@@ -1757,11 +1753,7 @@ foo
                 depends: vec![],
                 fields: Dcf::new(),
             };
-            let package1 = Package {
-                path: PathBuf::from("/mock/path1"),
-                description: description1,
-                namespace: namespace1,
-            };
+            let package1 = Package::new(PathBuf::from("/mock/path1"), description1, namespace1);
 
             // pkg2 exports `bar` and `baz`
             let namespace2 = Namespace {
@@ -1775,11 +1767,7 @@ foo
                 depends: vec![],
                 fields: Dcf::new(),
             };
-            let package2 = Package {
-                path: PathBuf::from("/mock/path2"),
-                description: description2,
-                namespace: namespace2,
-            };
+            let package2 = Package::new(PathBuf::from("/mock/path2"), description2, namespace2);
 
             let library = Library::new(vec![])
                 .insert("pkg1", package1)
@@ -1835,11 +1823,7 @@ foo
                 depends: vec![],
                 fields: Dcf::new(),
             };
-            let package = Package {
-                path: PathBuf::from("/mock/path"),
-                description,
-                namespace,
-            };
+            let package = Package::new(PathBuf::from("/mock/path"), description, namespace);
 
             let library = Library::new(vec![]).insert("pkg", package);
 

crates/ark/src/lsp/inputs/documentation.rs

@@ -0,0 +1,82 @@
+use std::path::Path;
+
+use crate::lsp::inputs::documentation_rd_file::RdFile;
+
+#[derive(Default, Clone, Debug)]
+pub struct Documentation {
+    pub rd_files: Vec<RdFile>,
+}
+
+impl Documentation {
+    /// Load .Rd files from the man directory
+    pub fn load_from_folder(path: &Path) -> anyhow::Result<Self> {
+        if !path.is_dir() {
+            return Ok(Documentation::default());
+        }
+
+        let mut rd_files = Vec::new();
+
+        for entry in std::fs::read_dir(&path)? {
+            let entry = entry?;
+            let path = entry.path();
+            if path.is_file() && path.extension().and_then(|s| s.to_str()) == Some("Rd") {
+                rd_files.push(RdFile::load_from_file(&path)?);
+            }
+        }
+
+        Ok(Documentation { rd_files })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::fs::File;
+    use std::io::Write;
+
+    use tempfile::tempdir;
+
+    use super::*;
+    use crate::lsp::inputs::documentation_rd_file::RdDocType;
+
+    fn create_rd_file(dir: &std::path::Path, name: &str, content: &str) {
+        let file_path = dir.join(name);
+        let mut file = File::create(&file_path).unwrap();
+        file.write_all(content.as_bytes()).unwrap();
+    }
+
+    #[test]
+    fn test_load_from_folder_with_rd_files() {
+        let dir = tempdir().unwrap();
+        create_rd_file(dir.path(), "foo.Rd", "\\name{foo}\n\\docType{data}");
+        create_rd_file(dir.path(), "bar.Rd", "\\name{bar}\n\\docType{package}");
+        create_rd_file(dir.path(), "baz.Rd", "\\name{baz}\n% Some Rd file");
+        create_rd_file(dir.path(), "qux.txt", "Not an Rd file");
+
+        let documentation = Documentation::load_from_folder(dir.path()).unwrap();
+        assert_eq!(documentation.rd_files.len(), 3);
+
+        let doc_types: Vec<(Option<String>, Option<RdDocType>)> = documentation
+            .rd_files
+            .into_iter()
+            .map(|rd| (rd.name, rd.doc_type))
+            .collect();
+
+        assert!(doc_types.contains(&(Some(String::from("foo")), Some(RdDocType::Data))));
+        assert!(doc_types.contains(&(Some(String::from("bar")), Some(RdDocType::Package))));
+        assert!(doc_types.contains(&(Some(String::from("baz")), None)));
+    }
+
+    #[test]
+    fn test_load_from_folder_empty_or_nonexistent() {
+        let dir = tempdir().unwrap();
+
+        // No files in directory
+        let documentation = Documentation::load_from_folder(dir.path()).unwrap();
+        assert_eq!(documentation.rd_files.len(), 0);
+
+        // Nonexistent directory
+        let nonexistent = dir.path().join("does_not_exist");
+        let documentation = Documentation::load_from_folder(&nonexistent).unwrap();
+        assert_eq!(documentation.rd_files.len(), 0);
+    }
+}

crates/ark/src/lsp/inputs/documentation_rd_file.rs

@@ -1,11 +1,17 @@
 use std::fs;
 use std::path::Path;
 
+#[derive(Clone, Debug)]
 pub struct RdFile {
+    /// `name` and `title` are mandatory in a properly written documentation
+    /// file but we make them optional here in case they are missing. We
+    /// currently don't load `title` because it's possible it contains escaped
+    /// `\` characters and we don't have a proper Rd parser yet.
+    pub name: Option<String>,
     pub doc_type: Option<RdDocType>,
 }
 
-#[derive(Debug, PartialEq)]
+#[derive(Clone, Debug, PartialEq)]
 pub enum RdDocType {
     Data,
     Package,
@@ -20,11 +26,23 @@ impl RdFile {
             )
         })?;
 
+        let name = parse_name(&content);
         let doc_type = parse_doc_type(&content);
-        Ok(RdFile { doc_type })
+
+        Ok(RdFile { name, doc_type })
     }
 }
 
+fn parse_name(content: &str) -> Option<String> {
+    static RE: std::sync::LazyLock<regex::Regex> =
+        std::sync::LazyLock::new(|| regex::Regex::new(r"\\name\{([a-zA-Z0-9_]+)\}").unwrap());
+
+    let captures = RE.captures(content)?;
+    let name = captures.get(1)?.as_str().to_string();
+
+    Some(name)
+}
+
 fn parse_doc_type(content: &str) -> Option<RdDocType> {
     static RE: std::sync::LazyLock<regex::Regex> =
         std::sync::LazyLock::new(|| regex::Regex::new(r"\\docType\{(data|package)\}").unwrap());
@@ -42,6 +60,44 @@ fn parse_doc_type(content: &str) -> Option<RdDocType> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn test_parse_name_basic() {
+        let input = r#"\name{foobar}"#;
+        assert_eq!(parse_name(input), Some("foobar".to_string()));
+
+        let input = r#"
+            % Some Rd file
+            \name{mydata}
+            \docType{data}
+        "#;
+        assert_eq!(parse_name(input), Some("mydata".to_string()));
+    }
+
+    #[test]
+    fn test_parse_name_escaped_brace() {
+        let input = r#"\name{foo\}bar}"#;
+        assert_eq!(parse_name(input), None);
+    }
+
+    #[test]
+    fn test_parse_name_missing() {
+        let input = r#"
+            % typo
+            \namee{data}
+        "#;
+        assert_eq!(parse_name(input), None);
+    }
+
+    #[test]
+    fn test_parse_name_multiple_names() {
+        let input = r#"
+            \name{first}
+            \name{second}
+        "#;
+        // Should match the first occurrence
+        assert_eq!(parse_name(input), Some("first".to_string()));
+    }
+
     #[test]
     fn test_parse_doc_type_data() {
         let input = r#"\docType{data}"#;

crates/ark/src/lsp/inputs/mod.rs

@@ -5,6 +5,7 @@
 //
 //
 
+pub mod documentation;
 pub mod documentation_rd_file;
 pub mod library;
 pub mod package;

crates/ark/src/lsp/inputs/package.rs

@@ -8,6 +8,7 @@
 use std::fs;
 use std::path::PathBuf;
 
+use crate::lsp::inputs::documentation::Documentation;
 use crate::lsp::inputs::package_description::Description;
 use crate::lsp::inputs::package_namespace::Namespace;
 
@@ -20,13 +21,22 @@ pub struct Package {
 
     pub description: Description,
     pub namespace: Namespace,
+    pub documentation: Documentation,
 }
 
 impl Package {
+    pub fn new(path: PathBuf, description: Description, namespace: Namespace) -> Self {
+        Self {
+            path,
+            description,
+            namespace,
+            documentation: Default::default(),
+        }
+    }
+
     /// Load a package from a given path.
     pub fn load_from_folder(package_path: &std::path::Path) -> anyhow::Result<Option<Self>> {
         let description_path = package_path.join("DESCRIPTION");
-        let namespace_path = package_path.join("NAMESPACE");
 
         // Only consider directories that contain a description file
         if !description_path.is_file() {
@@ -38,6 +48,7 @@ impl Package {
         let description_contents = fs::read_to_string(&description_path)?;
         let description = Description::parse(&description_contents)?;
 
+        let namespace_path = package_path.join("NAMESPACE");
         let namespace = if namespace_path.is_file() {
             let namespace_contents = fs::read_to_string(&namespace_path)?;
             Namespace::parse(&namespace_contents)?
@@ -49,10 +60,20 @@ impl Package {
             Namespace::default()
         };
 
+        let documentation_path = package_path.join("man");
+        let documentation = match Documentation::load_from_folder(&documentation_path) {
+            Ok(documentation) => documentation,
+            Err(err) => {
+                tracing::warn!("Can't load package documentation: {err:?}");
+                Documentation::default()
+            },
+        };
+
         Ok(Some(Package {
             path: package_path.to_path_buf(),
             description,
             namespace,
+            documentation,
         }))
     }