feat: show doc comments in LSP (#5968)

# Description

## Problem

Part of #5797

## Summary


![lsp-doc-comments](https://github.com/user-attachments/assets/9560d41a-3163-4489-820e-a0f488b98f1a)

This is just an experiment! 

We now parse doc comments, like we parse attributes, and attach them to
AST nodes. From there we store them in `NodeInterner` (for now only if
in LSP mode). Then we retrieve those comments for hover and
autocompletion.

## Additional Context

I decided to always store the doc comments in the NodeInterner.

I've been thinking and maybe the doc comments shouldn't be parsed as
`String`, but instead be a `Span`. Then we wouldn't need to allocate a
string for them, and only read from the source file when needed. But...
that's an optimization that can be done later.

After merging this, the next steps could be:
1. Copy the doc comments found in the many `.md` files into the standard
library (they will be duplicated, but just for a wihle)
2. Create a script or something that generates the `.md` files from the
doc comments

Note: I removed the lalrpop code because I got some errors and I thought
maybe it's not very useful to keep that code around if we have to make
changes to it to maintain it, but it's not working (we could always
revive it from git's history). But let me know if this is wrong.

## Documentation

Check one:
- [x] No documentation needed.
- [ ] Documentation included in this PR.
- [ ] **[For Experimental Features]** Documentation to be submitted in a
separate PR.

# PR Checklist

- [x] I have tested the changes locally.
- [x] I have formatted the changes with [Prettier](https://prettier.io/)
and/or `cargo fmt` on default settings.

---------

Co-authored-by: Tom French <[email protected]>

aztec_macros/src/lib.rs

@@ -66,7 +66,9 @@ fn transform(
 
     // Usage -> mut ast -> aztec_library::transform(&mut ast)
     // Covers all functions in the ast
-    for submodule in ast.submodules.iter_mut().filter(|submodule| submodule.is_contract) {
+    for submodule in
+        ast.submodules.iter_mut().map(|m| &mut m.item).filter(|submodule| submodule.is_contract)
+    {
         if transform_module(
             &file_id,
             &mut submodule.contents,
@@ -111,7 +113,8 @@ fn transform_module(
     }
 
     let has_initializer = module.functions.iter().any(|func| {
-        func.def
+        func.item
+            .def
             .attributes
             .secondary
             .iter()
@@ -121,6 +124,7 @@ fn transform_module(
     let mut stubs: Vec<_> = vec![];
 
     for func in module.functions.iter_mut() {
+        let func = &mut func.item;
         let mut is_private = false;
         let mut is_public = false;
         let mut is_initializer = false;
@@ -175,6 +179,7 @@ fn transform_module(
         let private_functions: Vec<_> = module
             .functions
             .iter()
+            .map(|t| &t.item)
             .filter(|func| {
                 func.def
                     .attributes
@@ -187,6 +192,7 @@ fn transform_module(
         let public_functions: Vec<_> = module
             .functions
             .iter()
+            .map(|func| &func.item)
             .filter(|func| {
                 func.def
                     .attributes

aztec_macros/src/transforms/compute_note_hash_and_optionally_a_nullifier.rs

@@ -166,7 +166,7 @@ fn generate_compute_note_hash_and_optionally_a_nullifier(
     assert_eq!(errors.len(), 0, "Failed to parse Noir macro code. This is either a bug in the compiler or the Noir macro code");
 
     let mut function_ast = function_ast.into_sorted();
-    function_ast.functions.remove(0)
+    function_ast.functions.remove(0).item
 }
 
 fn generate_compute_note_hash_and_optionally_a_nullifier_source(

aztec_macros/src/transforms/contract_interface.rs

@@ -1,7 +1,7 @@
 use acvm::acir::AcirField;
 
 use noirc_errors::Location;
-use noirc_frontend::ast::{Ident, NoirFunction, UnresolvedTypeData};
+use noirc_frontend::ast::{Documented, Ident, NoirFunction, UnresolvedTypeData};
 use noirc_frontend::{
     graph::CrateId,
     macros_api::{FieldElement, FileId, HirContext, HirExpression, HirLiteral, HirStatement},
@@ -267,15 +267,16 @@ pub fn generate_contract_interface(
         .methods
         .iter()
         .enumerate()
-        .map(|(i, (method, orig_span))| {
+        .map(|(i, (documented_method, orig_span))| {
+            let method = &documented_method.item;
             if method.name() == "at" || method.name() == "interface" || method.name() == "storage" {
-                (method.clone(), *orig_span)
+                (documented_method.clone(), *orig_span)
             } else {
                 let (_, new_location) = stubs[i];
                 let mut modified_method = method.clone();
                 modified_method.def.name =
                     Ident::new(modified_method.name().to_string(), new_location.span);
-                (modified_method, *orig_span)
+                (Documented::not_documented(modified_method), *orig_span)
             }
         })
         .collect();

aztec_macros/src/transforms/events.rs

@@ -1,4 +1,4 @@
-use noirc_frontend::ast::{ItemVisibility, NoirFunction, NoirTraitImpl, TraitImplItem};
+use noirc_frontend::ast::{Documented, ItemVisibility, NoirFunction, NoirTraitImpl, TraitImplItem};
 use noirc_frontend::macros_api::{NodeInterner, StructId};
 use noirc_frontend::token::SecondaryAttribute;
 use noirc_frontend::{
@@ -34,10 +34,11 @@ pub fn generate_event_impls(
     //     print!("\ngenerate_event_interface_impl COUNT: {}\n", event_struct.name.0.contents);
     // }
 
-    for submodule in module.submodules.iter_mut() {
-        let annotated_event_structs = submodule.contents.types.iter_mut().filter(|typ| {
-            typ.attributes.iter().any(|attr| is_custom_attribute(attr, "aztec(event)"))
-        });
+    for submodule in module.submodules.iter_mut().map(|m| &mut m.item) {
+        let annotated_event_structs =
+            submodule.contents.types.iter_mut().map(|typ| &mut typ.item).filter(|typ| {
+                typ.attributes.iter().any(|attr| is_custom_attribute(attr, "aztec(event)"))
+            });
 
         for event_struct in annotated_event_structs {
             // event_struct.attributes.push(SecondaryAttribute::Abi("events".to_string()));
@@ -52,7 +53,9 @@ pub fn generate_event_impls(
 
             let mut event_fields = vec![];
 
-            for (field_ident, field_type) in event_struct.fields.iter() {
+            for field in event_struct.fields.iter() {
+                let field_ident = &field.item.name;
+                let field_type = &field.item.typ;
                 event_fields.push((
                     field_ident.0.contents.to_string(),
                     field_type.typ.to_string().replace("plain::", ""),
@@ -64,18 +67,30 @@ pub fn generate_event_impls(
                 event_byte_len,
                 empty_spans,
             )?;
-            event_interface_trait_impl.items.push(TraitImplItem::Function(
-                generate_fn_get_event_type_id(event_type.as_str(), event_len, empty_spans)?,
+            event_interface_trait_impl.items.push(Documented::not_documented(
+                TraitImplItem::Function(generate_fn_get_event_type_id(
+                    event_type.as_str(),
+                    event_len,
+                    empty_spans,
+                )?),
+            ));
+            event_interface_trait_impl.items.push(Documented::not_documented(
+                TraitImplItem::Function(generate_fn_private_to_be_bytes(
+                    event_type.as_str(),
+                    event_byte_len,
+                    empty_spans,
+                )?),
             ));
-            event_interface_trait_impl.items.push(TraitImplItem::Function(
-                generate_fn_private_to_be_bytes(event_type.as_str(), event_byte_len, empty_spans)?,
+            event_interface_trait_impl.items.push(Documented::not_documented(
+                TraitImplItem::Function(generate_fn_to_be_bytes(
+                    event_type.as_str(),
+                    event_byte_len,
+                    empty_spans,
+                )?),
             ));
-            event_interface_trait_impl.items.push(TraitImplItem::Function(
-                generate_fn_to_be_bytes(event_type.as_str(), event_byte_len, empty_spans)?,
+            event_interface_trait_impl.items.push(Documented::not_documented(
+                TraitImplItem::Function(generate_fn_emit(event_type.as_str(), empty_spans)?),
             ));
-            event_interface_trait_impl
-                .items
-                .push(TraitImplItem::Function(generate_fn_emit(event_type.as_str(), empty_spans)?));
             submodule.contents.trait_impls.push(event_interface_trait_impl);
 
             let serialize_trait_impl = generate_trait_impl_serialize(
@@ -245,7 +260,7 @@ fn generate_fn_get_event_type_id(
     }
 
     let mut function_ast = function_ast.into_sorted();
-    let mut noir_fn = function_ast.functions.remove(0);
+    let mut noir_fn = function_ast.functions.remove(0).item;
     noir_fn.def.visibility = ItemVisibility::Public;
     Ok(noir_fn)
 }
@@ -292,7 +307,7 @@ fn generate_fn_private_to_be_bytes(
     }
 
     let mut function_ast = function_ast.into_sorted();
-    let mut noir_fn = function_ast.functions.remove(0);
+    let mut noir_fn = function_ast.functions.remove(0).item;
     noir_fn.def.visibility = ItemVisibility::Public;
     Ok(noir_fn)
 }
@@ -337,7 +352,7 @@ fn generate_fn_to_be_bytes(
     }
 
     let mut function_ast = function_ast.into_sorted();
-    let mut noir_fn = function_ast.functions.remove(0);
+    let mut noir_fn = function_ast.functions.remove(0).item;
     noir_fn.def.visibility = ItemVisibility::Public;
     Ok(noir_fn)
 }
@@ -361,7 +376,7 @@ fn generate_fn_emit(event_type: &str, empty_spans: bool) -> Result<NoirFunction,
     }
 
     let mut function_ast = function_ast.into_sorted();
-    let mut noir_fn = function_ast.functions.remove(0);
+    let mut noir_fn = function_ast.functions.remove(0).item;
     noir_fn.def.visibility = ItemVisibility::Public;
     Ok(noir_fn)
 }