Feature add doccomments

src/flattening/flatten.rs

@@ -667,7 +667,7 @@ impl<'l, 'errs> FlatteningContext<'l, 'errs> {
                 })} else {None};
             // Parsing components done
 
-            let documentation = cursor.extract_gathered_comments();
+            let documentation = cursor.extract_doc_comments();
 
             let typ_expr = match typ_or_module_expr {
                 ModuleOrWrittenType::WrittenType(typ) => {
@@ -813,7 +813,7 @@ impl<'l, 'errs> FlatteningContext<'l, 'errs> {
         match self.flatten_wire_reference(cursor) {
             PartialWireReference::Error => None,
             PartialWireReference::GlobalModuleName(module_ref) => {
-                let documentation = cursor.extract_gathered_comments();
+                let documentation = cursor.extract_doc_comments();
                 let interface_span = module_ref.get_total_span();
                 let submodule_decl = self.alloc_submodule_instruction(module_ref, None, documentation);
                 Some(ModuleInterfaceReference {
@@ -1240,7 +1240,7 @@ impl<'l, 'errs> FlatteningContext<'l, 'errs> {
         self.local_variable_context.pop_frame(old_frame);
     }
     fn flatten_code_keep_context(&mut self, cursor: &mut Cursor) {
-        cursor.clear_gathered_comments(); // Clear comments at the start of a block
+        cursor.clear_doc_comments(); // Clear comments at the start of a block
         cursor.list(kind!("block"), |cursor| {
             let kind = cursor.kind();
             if kind == kind!("assign_left_side") {
@@ -1321,7 +1321,7 @@ impl<'l, 'errs> FlatteningContext<'l, 'errs> {
             } else {
                 cursor.could_not_match()
             }
-            cursor.clear_gathered_comments(); // Clear comments after every statement, so comments don't bleed over
+            cursor.clear_doc_comments(); // Clear comments after every statement, so comments don't bleed over
         });
     }
 
@@ -1492,7 +1492,7 @@ impl<'l, 'errs> FlatteningContext<'l, 'errs> {
                     is_port: DeclarationPortInfo::NotPort,
                     identifier_type: IdentifierType::Generative,
                     latency_specifier: None,
-                    documentation: const_type_cursor.extract_gathered_comments(),
+                    documentation: const_type_cursor.extract_doc_comments(),
                 }));
 
                 self.alloc_local_name(name_span, NamedLocal::Declaration(module_output_decl));

src/flattening/initialization.rs

@@ -302,7 +302,7 @@ fn initialize_global_object(builder: &mut FileBuilder, parsing_errors: ErrorColl
         type_variable_alloc: TypingAllocator{domain_variable_alloc: UUIDAllocator::new(), type_variable_alloc: UUIDAllocator::new()},
         template_arguments: ctx.template_inputs,
         instructions: FlatAlloc::new(),
-        documentation: cursor.extract_gathered_comments(),
+        documentation: cursor.extract_doc_comments(),
         file: builder.file_id,
         name,
         name_span,

src/flattening/parser.rs

@@ -35,7 +35,7 @@ fn print_current_node_indented<'ft>(file_text: &'ft FileText, cursor: &TreeCurso
 pub struct Cursor<'t> {
     cursor: TreeCursor<'t>,
     file_text: &'t FileText,
-    gathered_comments: Vec<Span>,
+    doc_comments: Vec<Span>,
     current_field_was_already_consumed: bool,
 }
 
@@ -44,7 +44,7 @@ impl<'t> Cursor<'t> {
         Self {
             cursor: tree.walk(),
             file_text,
-            gathered_comments: Vec::new(),
+            doc_comments: Vec::new(),
             current_field_was_already_consumed: false,
         }
     }
@@ -280,23 +280,24 @@ impl<'t> Cursor<'t> {
         let node = self.cursor.node();
         let kind = node.kind_id();
 
-        if kind == kind!("single_line_comment") || kind == kind!("multi_line_comment") {
-            let mut range = node.byte_range();
-            range.start += 2; // skip '/*' or '//'
-            if kind == kind!("multi_line_comment") {
-                range.end -= 2; // skip '*/'
+        if let kind!("doc_comment")|kind!("multi_line_comment")|kind!("single_line_comment") = kind {
+            if kind == kind!("doc_comment") {
+                let mut range = node.byte_range();
+                range.start += 3; // skip '///'
+                self.doc_comments.push(Span::from(range));
+            } else {
+                self.clear_doc_comments();
             }
-            self.gathered_comments.push(Span::from(range));
         }
     }
 
-    pub fn extract_gathered_comments(&mut self) -> Documentation {
-        let gathered = self.gathered_comments.clone().into_boxed_slice();
-        self.gathered_comments.clear();
+    pub fn extract_doc_comments(&mut self) -> Documentation {
+        let gathered = self.doc_comments.clone().into_boxed_slice();
+        self.doc_comments.clear();
         Documentation { gathered }
     }
-    pub fn clear_gathered_comments(&mut self) {
-        self.gathered_comments.clear()
+    pub fn clear_doc_comments(&mut self) {
+        self.doc_comments.clear()
     }
 
     // Error reporting

stl/core.sus

@@ -1,10 +1,10 @@
 
-// Compiler Intrinsic
+/// Compiler Intrinsic
 __builtin__ module LatencyOffset #(T, int OFFSET) {
     interface LatencyOffset : T in'0 -> T out'OFFSET
 }
 
-// Compiler Intrinsic
+/// Compiler Intrinsic
 __builtin__ module CrossDomain #(T) {
     interface in_domain : T in'0
     domain out
@@ -22,12 +22,12 @@ __builtin__ module BitsToInt {
 // For now these builtin declarations must be in this order, because they're constants in the code. 
 // We'll get a better system for this at some point
 
-// The decider of truth and falsity
+/// The decider of truth and falsity
 __builtin__ struct bool {}
-// An integer of variable size. Right now it's not implemented yet, so this is just a 32-bit int. 
+/// An integer of variable size. Right now it's not implemented yet, so this is just a 32-bit int. 
 __builtin__ struct int {}
 
-// True, as in '1'
+/// True, as in '1'
 __builtin__ const bool true {}
-// False, as in '0'
+/// False, as in '0'
 __builtin__ const bool false {}

stl/util.sus

@@ -178,7 +178,7 @@ module Abs {
 	}
 }
 
-// Temporary, to be replaced with slice syntax : result = vals[FROM +: OUT_SIZE]
+/// Temporary, to be replaced with slice syntax : result = vals[FROM +: OUT_SIZE]
 module Slice #(T, int SIZE, int OUT_SIZE, int FROM) {
 	interface Slice : T[SIZE] vals -> T[OUT_SIZE] result
 
@@ -231,7 +231,7 @@ module PopCount #(int WIDTH) {
 }
 
 
-// Recursive Tree Add module recurses smaller copies of itself. 
+/// Recursive Tree Add module recurses smaller copies of itself. 
 module TreeAdd #(int WIDTH) {
 	interface TreeAdd : int[WIDTH] values'0 -> int total
 

test.sus

@@ -13,7 +13,7 @@ module example_md {
 }
 
 
-// (a*b) + c
+/// (a*b) + c
 module multiply_add {
 	interface multiply_add : int a, int b, int c -> int total
 
@@ -92,7 +92,7 @@ module Accumulator {
 }
 
 
-//timeline (a, true -> /) | (a, false -> /) .. (a, false -> r)* .. (a, true -> r)
+///timeline (a, true -> /) | (a, false -> /) .. (a, false -> r)* .. (a, true -> r)
 module blur {
     interface blur : int a, bool done -> int result 
 	state bool working
@@ -108,7 +108,7 @@ module blur {
 
 
 
-//timeline (X -> X) .. (/ -> X) .. (/ -> X) .. (/ -> X)
+///timeline (X -> X) .. (/ -> X) .. (/ -> X) .. (/ -> X)
 module Unpack4 {
     interface Unpack4 : int[4] packed -> int out_stream 
 	gen int INITIAL = 0
@@ -180,7 +180,7 @@ module test_various_assignments {
 	reg int a, st[2], reg reg b = assignment_producer()
 }
 
-//timeline (bs -> /, true) | (bs -> v, false)
+///timeline (bs -> /, true) | (bs -> v, false)
 module first_bit_idx_6 {
     interface first_bit_idx_6 : bool[6] bits -> int first, bool all_zeros 
 	if bits[0] {
@@ -243,7 +243,7 @@ module permute {
 	permuted_mbf = mbf
 }
 
-//timeline (X, [false24], true -> /, false) | (X, vs, true -> X, true) .. (/, /, false -> X, true)*
+///timeline (X, [false24], true -> /, false) | (X, vs, true -> X, true) .. (/, /, false -> X, true)*
 module permute24 {
     interface permute24 : bool[128] mbf, bool[24] valid_permutes, bool start -> bool[128] permuted_out, bool permuted_out_valid 
 	state bool[128] stored_mbf
@@ -310,7 +310,7 @@ module determinable_input_latency {
     y = t
 }
 
-// This module is a copy of ::undeteriminable_input_latency, but it doesn't have an error, because we just assume the latency of the inner nodes to be the earliest possible. 
+/// This module is a copy of ::undeteriminable_input_latency, but it doesn't have an error, because we just assume the latency of the inner nodes to be the earliest possible. 
 module determinable_because_no_input_output_ports {
     interface determinable_because_no_input_output_ports : int a -> int x 
 	reg int a_d = a
@@ -320,7 +320,7 @@ module determinable_because_no_input_output_ports {
     x = t_d + a_dd
 }
 
-// This module is a copy of ::undeteriminable_input_latency, but it doesn't have an error, because we just assume the latency of the inner nodes to be the earliest possible. 
+/// This module is a copy of ::undeteriminable_input_latency, but it doesn't have an error, because we just assume the latency of the inner nodes to be the earliest possible. 
 module conflicting_latency_declarations {
     interface conflicting_latency_declarations : int a'0 -> int x'1 
 	reg int nio = a
@@ -421,13 +421,13 @@ module multiple_outputs_only {
 }
 
 
-// Test submodule comment
+/// Test submodule comment
 module submodule {
     interface submodule : int a, int b -> int r 
 	r = a * b
 }
 
-// module doing nothing
+/// module doing nothing
 module doNothing {}
 
 /*
@@ -572,7 +572,7 @@ module use_my_mod {
 	either = x | y
 }
 
-// Main module documentation
+/// Main module documentation
 module submodule_named_ports {
     interface submodule_named_ports : int port_a, int port_b -> int port_c 
 	port_c = port_a + port_b
@@ -582,7 +582,7 @@ module submodule_named_ports {
 
 module use_submodule_named_ports {
     interface use_submodule_named_ports : int i -> int o 
-// Test submodule documentation
+/// Test submodule documentation
 	submodule_named_ports sm
 
 	o = sm(i, i)
@@ -596,7 +596,7 @@ module use_submodule_named_ports {
 
 module contains_submodule_submodule {
     interface contains_submodule_submodule : int a, int b, int c -> int r 
-	// Temp val
+	/// Temp val
     int tmp = submodule(a, b)
 	doNothing()
 	reg r = tmp + c
@@ -912,7 +912,7 @@ module run_instruction {
 	}
 }
 
-// Test no main interface error
+/// Test no main interface error
 module no_main_interface {
 	//interface no_main_interface
 }

tree-sitter-sus/grammar.js

@@ -329,6 +329,7 @@ module.exports = grammar({
 
         // Extras
 
+        doc_comment: $ => /\/\/\/[^\n]*/,
         single_line_comment: $ => /\/\/[^\n]*/,
         multi_line_comment: $ => /\/\*[^\*]*\*+([^\/\*][^\*]*\*+)*\//,
     },
@@ -342,6 +343,7 @@ module.exports = grammar({
     extras: $ => [
         /[ \t\r]+/, // Non newline whitespace
         $.single_line_comment,
-        $.multi_line_comment
+        $.multi_line_comment,
+        $.doc_comment
     ]
 });