adds module docs

Author: roryc89

src/build/portable.rs

@@ -373,6 +373,7 @@ impl PModuleExports {
             method_own_constraints: self.method_own_constraints.iter().map(|(k, v)| {
                 (rest_qi(k, st), v.iter().map(|s| st.sym(*s)).collect())
             }).collect(),
+            module_doc: Vec::new(), // not persisted in portable format
         }
     }
 }

src/cst.rs

@@ -52,6 +52,8 @@ pub struct Module {
     pub decls: Vec<Decl>,
     /// All comments in the module source, in order of appearance (comment, span)
     pub comments: Vec<(Comment, Span)>,
+    /// Doc-comments that appear before the `module` keyword
+    pub doc_comments: Vec<Comment>,
 }
 
 /// Module name (potentially qualified: Data.Array)
@@ -102,6 +104,8 @@ pub enum DataMembers {
 pub struct ImportDecl {
     pub span: Span,
     pub module: ModuleName,
+    /// Span of the module name in the import (for hover support)
+    pub module_span: Span,
     pub imports: Option<ImportList>,
     pub qualified: Option<ModuleName>,
 }

src/lsp/handlers/hover.rs

@@ -212,6 +212,28 @@ impl Backend {
             if offset < import_decl.span.start || offset >= import_decl.span.end {
                 continue;
             }
+
+            // Check if cursor is on the module name
+            if offset >= import_decl.module_span.start && offset < import_decl.module_span.end {
+                let module_name = interner::resolve_module_name(&import_decl.module.parts);
+                let docs = self.get_imported_module_doc(&module_name).await;
+                let mut markdown = format!("```purescript\nmodule {module_name}\n```");
+                if !docs.is_empty() {
+                    markdown.push_str("\n\n---\n\n");
+                    for doc in &docs {
+                        markdown.push_str(doc.trim());
+                        markdown.push('\n');
+                    }
+                }
+                return Some(Hover {
+                    contents: HoverContents::Markup(MarkupContent {
+                        kind: MarkupKind::Markdown,
+                        value: markdown,
+                    }),
+                    range: None,
+                });
+            }
+
             let items = match &import_decl.imports {
                 Some(ImportList::Explicit(items)) | Some(ImportList::Hiding(items)) => items,
                 None => continue,
@@ -300,6 +322,43 @@ impl Backend {
             .collect()
     }
 
+    async fn get_imported_module_doc(&self, module_name: &str) -> Vec<String> {
+        // Try registry first (has module_doc from typechecking)
+        {
+            let module_parts: Vec<interner::Symbol> = module_name
+                .split('.')
+                .map(|s| interner::intern(s))
+                .collect();
+            let registry = self.registry.read().await;
+            if let Some(mod_exports) = registry.lookup(&module_parts) {
+                if !mod_exports.module_doc.is_empty() {
+                    return mod_exports.module_doc.clone();
+                }
+            }
+        }
+
+        // Fall back to parsing the source file
+        let target_uri = {
+            let mf = self.module_file_map.read().await;
+            mf.get(module_name).cloned()
+        };
+        let target_uri = match target_uri {
+            Some(u) => u,
+            None => return Vec::new(),
+        };
+        let target_source = match self.get_source_for_uri(&target_uri).await {
+            Some(s) => s,
+            None => return Vec::new(),
+        };
+        let target_module = match crate::parser::parse(&target_source) {
+            Ok(m) => m,
+            Err(_) => return Vec::new(),
+        };
+        target_module.doc_comments.iter().filter_map(|c| {
+            if let cst::Comment::Doc(text) = c { Some(text.clone()) } else { None }
+        }).collect()
+    }
+
     async fn get_local_kind(&self, module: &cst::Module, symbol: interner::Symbol) -> Option<String> {
         let registry = self.registry.read().await;
         let check_result = crate::typechecker::check_module_with_registry(module, &registry);

src/parser/grammar.lalrpop

@@ -29,6 +29,7 @@ pub Module: Module = {
             imports,
             decls,
             comments: Vec::new(),
+            doc_comments: Vec::new(),
         }
     }
 };
@@ -152,6 +153,7 @@ ImportDecl: ImportDecl = {
     <qualified:("as" <ModuleName>)?> <end:@R> => {
         ImportDecl {
             span: Span::new(start, end),
+            module_span: module.span,
             module: module.value,
             imports,
             qualified: qualified.map(|m| m.value),

src/parser/mod.rs

@@ -147,6 +147,14 @@ fn attach_comments(
     // Store all comments on the module
     module.comments = comment_pairs.clone();
 
+    // Attach doc-comments that appear before the `module` keyword to the module itself
+    let module_start = module.span.start;
+    module.doc_comments = comment_pairs
+        .iter()
+        .filter(|(c, span)| c.is_doc() && span.end <= module_start)
+        .map(|(c, _)| c.clone())
+        .collect();
+
     if module.decls.is_empty() {
         return;
     }
@@ -278,6 +286,40 @@ mod tests {
         assert_eq!(module.decls[0].doc_comments().len(), 2);
     }
 
+    #[test]
+    fn test_module_doc_comments() {
+        let module = parse("-- | This module does things\nmodule Main where\nfoo = 1").unwrap();
+        assert_eq!(module.doc_comments.len(), 1);
+        assert!(module.doc_comments[0].is_doc());
+        if let Comment::Doc(text) = &module.doc_comments[0] {
+            assert_eq!(text.trim(), "This module does things");
+        }
+    }
+
+    #[test]
+    fn test_module_multi_line_doc_comments() {
+        let module = parse("-- | Line 1\n-- | Line 2\nmodule Main where\nfoo = 1").unwrap();
+        assert_eq!(module.doc_comments.len(), 2);
+    }
+
+    #[test]
+    fn test_import_module_span() {
+        let module = parse("module Main where\nimport Data.Maybe").unwrap();
+        assert_eq!(module.imports.len(), 1);
+        let imp = &module.imports[0];
+        // "import Data.Maybe" — "Data.Maybe" starts at offset 25 (after "import ")
+        let src = "module Main where\nimport Data.Maybe";
+        assert_eq!(&src[imp.module_span.start..imp.module_span.end], "Data.Maybe");
+    }
+
+    #[test]
+    fn test_module_doc_not_confused_with_decl_doc() {
+        // Doc comment after `where` should attach to the decl, not the module
+        let module = parse("module Main where\n-- | Decl doc\nfoo = 1").unwrap();
+        assert_eq!(module.doc_comments.len(), 0);
+        assert_eq!(module.decls[0].doc_comments().len(), 1);
+    }
+
     // ===== Expression Tests: Literals =====
 
     #[test]

src/typechecker/check.rs

@@ -8094,6 +8094,7 @@ fn check_module_impl(module: &Module, registry: &ModuleRegistry, collect_span_ty
             .collect(),
         class_superclasses: class_superclasses.clone(),
         method_own_constraints: ctx.method_own_constraints.iter().map(|(k, v)| (qi(*k), v.clone())).collect(),
+        module_doc: Vec::new(), // filled in by the outer CST-level wrapper
     };
 
     // Ensure operator targets (e.g. Tuple for /\) are included in exported values and

src/typechecker/mod.rs

@@ -109,11 +109,18 @@ fn check_module_with_options(module: &crate::cst::Module, registry: &ModuleRegis
             span_types: HashMap::new(),
         };
     }
-    if collect_span_types {
+    let mut result = if collect_span_types {
         check::check_module_for_ide(&ast_module, registry)
     } else {
         check::check_module(&ast_module, registry)
-    }
+    };
+
+    // Propagate module-level doc-comments from CST to exports
+    result.exports.module_doc = module.doc_comments.iter().filter_map(|c| {
+        if let crate::cst::Comment::Doc(text) = c { Some(text.clone()) } else { None }
+    }).collect();
+
+    result
 }
 
 #[cfg(test)]

src/typechecker/registry.rs

@@ -76,6 +76,8 @@ pub struct ModuleExports {
     /// Method-level constraint class names from class definitions.
     /// Maps method name → constraint class names. Used for current_given_expanded in instance methods.
     pub method_own_constraints: HashMap<QualifiedIdent, Vec<Symbol>>,
+    /// Module-level doc-comments (appear before the `module` keyword)
+    pub module_doc: Vec<String>,
 }
 
 /// Registry of compiled modules, used to resolve imports.

tests/fixtures/lsp/hover/Simple.purs

@@ -137,6 +137,7 @@ getName = myRecord.name
 -- 56:8 (r) => hover: Int
 --
 -- Line 2: import Simple.Lib (class Cl, member, ...)
+-- 2:7 (Simple.Lib) => hover: module Simple.Lib | doc: Utility functions and classes for Simple
 -- 2:29 (member) => hover: member
 -- 2:53 (Effect) => hover: Type -> Type | doc: Opaque effect type
 -- 2:45 (addOne) => hover: addOne | doc: Adds one to a number

tests/fixtures/lsp/hover/Simple/Lib.purs

@@ -1,3 +1,4 @@
+-- | Utility functions and classes for Simple
 module Simple.Lib where
 
 import Prelude