diff --git a/rust/candid/src/binary_parser.rs b/rust/candid/src/binary_parser.rs
index ca8cd1636..26bcaaf03 100644
--- a/rust/candid/src/binary_parser.rs
+++ b/rust/candid/src/binary_parser.rs
@@ -188,6 +188,7 @@ impl ConsType {
                     let field = Field {
                         id: Label::Id(f.id).into(),
                         ty: f.index.to_type(len)?,
+                        comment: None,
                     };
                     res.push(field);
                 }
diff --git a/rust/candid/src/de.rs b/rust/candid/src/de.rs
index bb1fbf1cb..48a9c38ff 100644
--- a/rust/candid/src/de.rs
+++ b/rust/candid/src/de.rs
@@ -923,8 +923,8 @@ impl<'de> de::Deserializer<'de> for &mut Deserializer<'de> {
                     (TypeInner::Record(ref e), TypeInner::Record(ref w)) => {
                         match (&e[..], &w[..]) {
                             (
-                                [Field { id: e_id0, ty: ek }, Field { id: e_id1, ty: ev }],
-                                [Field { id: w_id0, ty: wk }, Field { id: w_id1, ty: wv }],
+                                [Field { id: e_id0, ty: ek, .. }, Field { id: e_id1, ty: ev, .. }],
+                                [Field { id: w_id0, ty: wk, .. }, Field { id: w_id1, ty: wv, .. }],
                             ) if **e_id0 == Label::Id(0)
                                 && **e_id1 == Label::Id(1)
                                 && **w_id0 == Label::Id(0)
diff --git a/rust/candid/src/pretty/candid.rs b/rust/candid/src/pretty/candid.rs
index 0f3b80ed2..106551947 100644
--- a/rust/candid/src/pretty/candid.rs
+++ b/rust/candid/src/pretty/candid.rs
@@ -74,10 +74,10 @@ pub(crate) fn pp_text(id: &str) -> RcDoc {
 }
 
 pub fn pp_ty(ty: &Type) -> RcDoc {
-    pp_ty_inner(ty.as_ref())
+    pp_ty_inner(ty.as_ref(), ty.comment())
 }
 
-pub fn pp_ty_inner(ty: &TypeInner) -> RcDoc {
+pub fn pp_ty_inner<'a>(ty: &'a TypeInner, comment: Option<&[String]>) -> RcDoc<'a> {
     use TypeInner::*;
     match ty {
         Null => str("null"),
@@ -103,7 +103,7 @@ pub fn pp_ty_inner(ty: &TypeInner) -> RcDoc {
         Vec(ref t) if matches!(t.as_ref(), Nat8) => str("blob"),
         Vec(ref t) => kwd("vec").append(pp_ty(t)),
         Record(ref fs) => {
-            let t = Type(ty.clone().into());
+            let t = Type::from((ty.clone(), comment));
             if t.is_tuple() {
                 let tuple = concat(fs.iter().map(|f| pp_ty(&f.ty)), ";");
                 kwd("record").append(enclose_space("{", tuple, "}"))
@@ -141,7 +141,9 @@ pub(crate) fn pp_field(field: &Field, is_variant: bool) -> RcDoc {
     } else {
         kwd(" :").append(pp_ty(&field.ty))
     };
-    pp_label(&field.id).append(ty_doc)
+    pp_comment(field.comment())
+        .append(pp_label(&field.id))
+        .append(ty_doc)
 }
 
 fn pp_fields(fs: &[Field], is_variant: bool) -> RcDoc {
@@ -195,7 +197,10 @@ fn pp_service(serv: &[(String, Type)]) -> RcDoc {
                 TypeInner::Var(_) => pp_ty(func),
                 _ => unreachable!(),
             };
-            pp_text(id).append(kwd(" :")).append(func_doc)
+            pp_comment(func.comment())
+                .append(pp_text(id))
+                .append(kwd(" :"))
+                .append(func_doc)
         }),
         ";",
     );
@@ -204,7 +209,8 @@ fn pp_service(serv: &[(String, Type)]) -> RcDoc {
 
 fn pp_defs(env: &TypeEnv) -> RcDoc {
     lines(env.0.iter().map(|(id, ty)| {
-        kwd("type")
+        pp_comment(ty.comment())
+            .append(kwd("type"))
             .append(ident(id))
             .append(kwd("="))
             .append(pp_ty(ty))
@@ -220,6 +226,17 @@ fn pp_actor(ty: &Type) -> RcDoc {
     }
 }
 
+fn pp_comment(comment_lines: Option<&[String]>) -> RcDoc {
+    let mut comment_doc = RcDoc::nil();
+    if let Some(comment_lines) = comment_lines {
+        for line in comment_lines {
+            comment_doc =
+                comment_doc.append(RcDoc::text("// ").append(line).append(RcDoc::hardline()));
+        }
+    }
+    comment_doc
+}
+
 pub fn pp_init_args<'a>(env: &'a TypeEnv, args: &'a [ArgType]) -> RcDoc<'a> {
     pp_defs(env).append(pp_args(args))
 }
@@ -228,7 +245,9 @@ pub fn compile(env: &TypeEnv, actor: &Option<Type>) -> String {
         None => pp_defs(env).pretty(LINE_WIDTH).to_string(),
         Some(actor) => {
             let defs = pp_defs(env);
-            let actor = kwd("service :").append(pp_actor(actor));
+            let actor = pp_comment(actor.comment())
+                .append(kwd("service :"))
+                .append(pp_actor(actor));
             let doc = defs.append(actor);
             doc.pretty(LINE_WIDTH).to_string()
         }
diff --git a/rust/candid/src/pretty/utils.rs b/rust/candid/src/pretty/utils.rs
index 89e92fdf7..27f0f3cf1 100644
--- a/rust/candid/src/pretty/utils.rs
+++ b/rust/candid/src/pretty/utils.rs
@@ -54,9 +54,8 @@ pub fn concat<'a, D>(docs: D, sep: &'a str) -> RcDoc<'a>
 where
     D: Iterator<Item = RcDoc<'a>> + Clone,
 {
-    RcDoc::intersperse(docs.clone().map(|d| d.append(sep)), RcDoc::line()).flat_alt(
-        RcDoc::intersperse(docs, RcDoc::text(sep).append(RcDoc::line())),
-    )
+    RcDoc::intersperse(docs.clone().map(|d| d.append(sep)), RcDoc::line())
+        .flat_alt(strict_concat(docs, sep))
 }
 
 pub fn lines<'a, D>(docs: D) -> RcDoc<'a>
diff --git a/rust/candid/src/ser.rs b/rust/candid/src/ser.rs
index 53fee18ef..9a7cc0b3f 100644
--- a/rust/candid/src/ser.rs
+++ b/rust/candid/src/ser.rs
@@ -304,7 +304,7 @@ impl TypeSerialize {
 
                 sleb128_encode(&mut buf, Opcode::Record as i64)?;
                 leb128_encode(&mut buf, fs.len() as u64)?;
-                for Field { id, ty } in fs {
+                for Field { id, ty, .. } in fs {
                     leb128_encode(&mut buf, u64::from(id.get_id()))?;
                     self.encode(&mut buf, ty)?;
                 }
@@ -316,7 +316,7 @@ impl TypeSerialize {
 
                 sleb128_encode(&mut buf, Opcode::Variant as i64)?;
                 leb128_encode(&mut buf, fs.len() as u64)?;
-                for Field { id, ty } in fs {
+                for Field { id, ty, .. } in fs {
                     leb128_encode(&mut buf, u64::from(id.get_id()))?;
                     self.encode(&mut buf, ty)?;
                 }
diff --git a/rust/candid/src/types/impls.rs b/rust/candid/src/types/impls.rs
index 0682a4659..e0f5c65f7 100644
--- a/rust/candid/src/types/impls.rs
+++ b/rust/candid/src/types/impls.rs
@@ -193,10 +193,12 @@ macro_rules! map_impl {
                     Field {
                         id: Label::Id(0).into(),
                         ty: K::ty(),
+                        comment: None,
                     },
                     Field {
                         id: Label::Id(1).into(),
                         ty: V::ty(),
+                        comment: None,
                     },
                 ]).into();
                 TypeInner::Vec(tuple).into()
@@ -276,10 +278,12 @@ where
             Field {
                 id: Label::Named("Ok".to_owned()).into(),
                 ty: T::ty(),
+                comment: None,
             },
             Field {
                 id: Label::Named("Err".to_owned()).into(),
                 ty: E::ty(),
+                comment: None,
             },
         ])
         .into()
@@ -470,7 +474,7 @@ macro_rules! tuple_impls {
             {
                 fn _ty() -> Type {
                     TypeInner::Record(vec![
-                        $(Field{ id: Label::Id($n).into(), ty: $name::ty() },)+
+                        $(Field{ id: Label::Id($n).into(), ty: $name::ty(), comment: None },)+
                     ]).into()
                 }
                 fn idl_serialize<S>(&self, serializer: S) -> Result<(), S::Error>
@@ -512,10 +516,12 @@ impl CandidType for std::time::SystemTime {
             Field {
                 id: Label::Named("nanos_since_epoch".to_owned()).into(),
                 ty: u32::ty(),
+                comment: None,
             },
             Field {
                 id: Label::Named("secs_since_epoch".to_owned()).into(),
                 ty: u64::ty(),
+                comment: None,
             },
         ])
         .into()
@@ -547,10 +553,12 @@ impl CandidType for std::time::Duration {
             Field {
                 id: Label::Named("secs".to_owned()).into(),
                 ty: u64::ty(),
+                comment: None,
             },
             Field {
                 id: Label::Named("nanos".to_owned()).into(),
                 ty: u32::ty(),
+                comment: None,
             },
         ])
         .into()
diff --git a/rust/candid/src/types/internal.rs b/rust/candid/src/types/internal.rs
index 4a70cdba0..99b46054f 100644
--- a/rust/candid/src/types/internal.rs
+++ b/rust/candid/src/types/internal.rs
@@ -96,19 +96,20 @@ impl TypeContainer {
         self.go(&t)
     }
     fn go(&mut self, t: &Type) -> Type {
-        match t.as_ref() {
+        let inner = match t.as_ref() {
             TypeInner::Opt(t) => TypeInner::Opt(self.go(t)),
             TypeInner::Vec(t) => TypeInner::Vec(self.go(t)),
             TypeInner::Record(fs) => {
-                let res: Type = TypeInner::Record(
+                let record_inner = TypeInner::Record(
                     fs.iter()
-                        .map(|Field { id, ty }| Field {
+                        .map(|Field { id, ty, comment }| Field {
                             id: id.clone(),
                             ty: self.go(ty),
+                            comment: comment.clone(),
                         })
                         .collect(),
-                )
-                .into();
+                );
+                let res = (record_inner, t.comment()).into();
                 if t.is_tuple() {
                     return res;
                 }
@@ -123,15 +124,16 @@ impl TypeContainer {
                 }
             }
             TypeInner::Variant(fs) => {
-                let res: Type = TypeInner::Variant(
+                let variant_inner = TypeInner::Variant(
                     fs.iter()
-                        .map(|Field { id, ty }| Field {
+                        .map(|Field { id, ty, comment }| Field {
                             id: id.clone(),
                             ty: self.go(ty),
+                            comment: comment.clone(),
                         })
                         .collect(),
-                )
-                .into();
+                );
+                let res = (variant_inner, t.comment()).into();
                 let id = ID.with(|n| n.borrow().get(t).cloned());
                 if let Some(id) = id {
                     self.env.0.insert(id.to_string(), res);
@@ -174,13 +176,50 @@ impl TypeContainer {
                 self.go(ty),
             ),
             t => t.clone(),
-        }
-        .into()
+        };
+        (inner, t.comment()).into()
     }
 }
 
-#[derive(Debug, PartialEq, Hash, Eq, Clone, PartialOrd, Ord)]
-pub struct Type(pub std::rc::Rc<TypeInner>);
+type CommentLines = Vec<String>;
+
+#[derive(Clone)]
+pub struct Type(
+    pub std::rc::Rc<TypeInner>,
+    Option<std::rc::Rc<CommentLines>>,
+);
+
+impl PartialEq for Type {
+    fn eq(&self, other: &Self) -> bool {
+        self.0 == other.0
+    }
+}
+
+impl Eq for Type {}
+
+impl std::hash::Hash for Type {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.0.hash(state);
+    }
+}
+
+impl PartialOrd for Type {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for Type {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        self.0.cmp(&other.0)
+    }
+}
+
+impl std::fmt::Debug for Type {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
 
 #[derive(Debug, PartialEq, Hash, Eq, Clone, PartialOrd, Ord)]
 pub enum TypeInner {
@@ -227,7 +266,15 @@ impl AsRef<TypeInner> for Type {
 }
 impl From<TypeInner> for Type {
     fn from(t: TypeInner) -> Self {
-        Type(t.into())
+        Type(t.into(), None)
+    }
+}
+impl From<(TypeInner, Option<&[String]>)> for Type {
+    fn from((t, comment_lines): (TypeInner, Option<&[String]>)) -> Self {
+        Type(
+            t.into(),
+            comment_lines.map(|s| std::rc::Rc::new(s.to_vec())),
+        )
     }
 }
 impl TypeInner {
@@ -274,17 +321,19 @@ impl Type {
             Vec(t) => Vec(t.subst(tau)),
             Record(fs) => Record(
                 fs.iter()
-                    .map(|Field { id, ty }| Field {
+                    .map(|Field { id, ty, .. }| Field {
                         id: id.clone(),
                         ty: ty.subst(tau),
+                        comment: None,
                     })
                     .collect(),
             ),
             Variant(fs) => Variant(
                 fs.iter()
-                    .map(|Field { id, ty }| Field {
+                    .map(|Field { id, ty, .. }| Field {
                         id: id.clone(),
                         ty: ty.subst(tau),
+                        comment: None,
                     })
                     .collect(),
             ),
@@ -321,6 +370,9 @@ impl Type {
         }
         .into()
     }
+    pub fn comment(&self) -> Option<&[String]> {
+        self.1.as_ref().map(|rc| rc.as_slice())
+    }
 }
 #[cfg(feature = "printer")]
 impl fmt::Display for Type {
@@ -331,7 +383,11 @@ impl fmt::Display for Type {
 #[cfg(feature = "printer")]
 impl fmt::Display for TypeInner {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}", crate::pretty::candid::pp_ty_inner(self).pretty(80))
+        write!(
+            f,
+            "{}",
+            crate::pretty::candid::pp_ty_inner(self, None).pretty(80)
+        )
     }
 }
 #[cfg(not(feature = "printer"))]
@@ -476,6 +532,7 @@ pub type SharedLabel = std::rc::Rc<Label>;
 pub struct Field {
     pub id: SharedLabel,
     pub ty: Type,
+    pub comment: Option<std::rc::Rc<CommentLines>>,
 }
 #[cfg(feature = "printer")]
 impl fmt::Display for Field {
@@ -493,6 +550,11 @@ impl fmt::Display for Field {
         write!(f, "{:?}", self)
     }
 }
+impl Field {
+    pub fn comment(&self) -> Option<&[String]> {
+        self.comment.as_ref().map(|rc| rc.as_slice())
+    }
+}
 
 #[macro_export]
 /// Construct a field type, which can be used in `TypeInner::Record` and `TypeInner::Variant`.
@@ -506,7 +568,8 @@ macro_rules! field {
                 Ok(id) => $crate::types::Label::Id(id),
                 Err(_) => $crate::types::Label::Named(stringify!($id).to_string()),
             }.into(),
-            ty: $ty
+            ty: $ty,
+            comment: None,
         }
     }}
 }
@@ -662,17 +725,19 @@ pub fn unroll(t: &Type) -> Type {
         Vec(ref t) => Vec(unroll(t)),
         Record(fs) => Record(
             fs.iter()
-                .map(|Field { id, ty }| Field {
+                .map(|Field { id, ty, .. }| Field {
                     id: id.clone(),
                     ty: unroll(ty),
+                    comment: None,
                 })
                 .collect(),
         ),
         Variant(fs) => Variant(
             fs.iter()
-                .map(|Field { id, ty }| Field {
+                .map(|Field { id, ty, .. }| Field {
                     id: id.clone(),
                     ty: unroll(ty),
+                    comment: None,
                 })
                 .collect(),
         ),
diff --git a/rust/candid/src/types/result.rs b/rust/candid/src/types/result.rs
index 70eef1c17..11c12ab16 100644
--- a/rust/candid/src/types/result.rs
+++ b/rust/candid/src/types/result.rs
@@ -34,10 +34,12 @@ where
             Field {
                 id: Label::Named("ok".to_owned()).into(),
                 ty: T::ty(),
+                comment: None,
             },
             Field {
                 id: Label::Named("err".to_owned()).into(),
                 ty: E::ty(),
+                comment: None,
             },
         ])
         .into()
diff --git a/rust/candid/src/types/subtype.rs b/rust/candid/src/types/subtype.rs
index 1e002317d..d2641477f 100644
--- a/rust/candid/src/types/subtype.rs
+++ b/rust/candid/src/types/subtype.rs
@@ -78,8 +78,8 @@ fn subtype_(
             Ok(())
         }
         (Record(fs1), Record(fs2)) => {
-            let fields: HashMap<_, _> = fs1.iter().map(|Field { id, ty }| (id, ty)).collect();
-            for Field { id, ty: ty2 } in fs2 {
+            let fields: HashMap<_, _> = fs1.iter().map(|Field { id, ty, .. }| (id, ty)).collect();
+            for Field { id, ty: ty2, .. } in fs2 {
                 match fields.get(id) {
                     Some(ty1) => subtype_(report, gamma, env, ty1, ty2).with_context(|| {
                         format!("Record field {id}: {ty1} is not a subtype of {ty2}")
@@ -94,8 +94,8 @@ fn subtype_(
             Ok(())
         }
         (Variant(fs1), Variant(fs2)) => {
-            let fields: HashMap<_, _> = fs2.iter().map(|Field { id, ty }| (id, ty)).collect();
-            for Field { id, ty: ty1 } in fs1 {
+            let fields: HashMap<_, _> = fs2.iter().map(|Field { id, ty, .. }| (id, ty)).collect();
+            for Field { id, ty: ty1, .. } in fs1 {
                 match fields.get(id) {
                     Some(ty2) => subtype_(report, gamma, env, ty1, ty2).with_context(|| {
                         format!("Variant field {id}: {ty1} is not a subtype_ of {ty2}")
@@ -299,6 +299,7 @@ fn to_tuple(args: &[Type]) -> Type {
             .map(|(i, ty)| Field {
                 id: Label::Id(i as u32).into(),
                 ty: ty.clone(),
+                comment: None,
             })
             .collect(),
     )
diff --git a/rust/candid/src/types/value.rs b/rust/candid/src/types/value.rs
index d770dc26f..432881ce9 100644
--- a/rust/candid/src/types/value.rs
+++ b/rust/candid/src/types/value.rs
@@ -243,7 +243,7 @@ impl IDLValue {
                 let fields: HashMap<_, _> =
                     vec.iter().map(|IDLField { id, val }| (id, val)).collect();
                 let mut res = Vec::new();
-                for Field { id, ty } in fs.iter() {
+                for Field { id, ty, .. } in fs.iter() {
                     let val = fields
                         .get(id.as_ref())
                         .cloned()
@@ -341,6 +341,7 @@ impl IDLValue {
                     .map(|IDLField { id, val }| Field {
                         id: id.clone().into(),
                         ty: val.value_ty(),
+                        comment: None,
                     })
                     .collect();
                 TypeInner::Record(fs)
@@ -349,6 +350,7 @@ impl IDLValue {
                 let f = Field {
                     id: v.0.id.clone().into(),
                     ty: v.0.val.value_ty(),
+                    comment: None,
                 };
                 TypeInner::Variant(vec![f])
             }
diff --git a/rust/candid/tests/types.rs b/rust/candid/tests/types.rs
index 9c8fcb965..8a48dbca3 100644
--- a/rust/candid/tests/types.rs
+++ b/rust/candid/tests/types.rs
@@ -184,21 +184,34 @@ fn test_func() {
         }
         #[derive(CandidType)]
         pub struct Wrap(List<i8>);
+        /// Comment for NamedStruct
+        /// on multiple lines
         #[derive(CandidType)]
         pub struct NamedStruct {
+            /// Comment for NamedStruct.a
             pub a: u16,
+            /// Comment for NamedStruct.b
+            /// on multiple lines
             pub b: i32,
         }
+        /// Comment for A enum
         #[derive(CandidType)]
         pub enum A {
             A1(super::List<i8>, Box<List<i8>>, Wrap),
             A2(String, candid::Principal),
             A3(candid::Int),
-            // This struct happens to have the same candid type as NamedStruct
-            A4 { a: u16, b: i32 },
+            /// This struct happens to have the same candid type as NamedStruct
+            A4 {
+                a: u16,
+                b: i32,
+            },
+            /// This comment is for A5
             A5(NamedStruct),
             A6(Box<NamedStruct>),
-            A7 { b: i32, c: u16 },
+            A7 {
+                b: i32,
+                c: u16,
+            },
         }
     }
     use internal::A;
@@ -211,6 +224,8 @@ fn test_func() {
         unreachable!()
     }
 
+    /// Doc comment for id_struct
+    /// on multiple lines
     #[candid_method(query)]
     fn id_struct(_: (List<u8>,)) -> Result<List<u8>, candid::Empty> {
         unreachable!()
@@ -239,11 +254,14 @@ fn test_func() {
     fn init(_: List<i128>) {}
 
     candid::export_service!();
-    let expected = r#"type A = variant {
+    let expected = r#"// Comment for A enum
+type A = variant {
   A1 : record { List_1; Wrap; Wrap };
   A2 : record { text; principal };
   A3 : int;
-  A4 : NamedStruct;
+  // This struct happens to have the same candid type as NamedStruct
+  A4 : record { a : nat16; b : int32 };
+  // This comment is for A5
   A5 : NamedStruct;
   A6 : NamedStruct;
   A7 : record { b : int32; c : nat16 };
@@ -252,11 +270,21 @@ type Box = record { head : int8; tail : opt Box };
 type List = record { head : nat8; tail : opt List };
 type List_1 = record { head : int8; tail : opt List_1 };
 type List_2 = record { head : int; tail : opt List_2 };
-type NamedStruct = record { a : nat16; b : int32 };
+// Comment for NamedStruct
+// on multiple lines
+type NamedStruct = record {
+  // Comment for NamedStruct.a
+  a : nat16;
+  // Comment for NamedStruct.b
+  // on multiple lines
+  b : int32;
+};
 type Result = variant { Ok : List; Err : empty };
 type Result_1 = variant { Ok : record { record { A }; A }; Err : text };
 type Wrap = record { head : int8; tail : opt Box };
 service : (List_2) -> {
+  // Doc comment for id_struct
+  // on multiple lines
   id_struct : (record { List }) -> (Result) query;
   id_struct_composite : (record { List }) -> (Result) composite_query;
   id_struct_destructure : (NamedStruct) -> (nat16, int32);
@@ -279,6 +307,7 @@ fn test_counter() {
             Service { counter: 0 }
         }
         #[candid_method]
+        /// Doc comment for inc
         fn inc(&mut self) {
             self.counter += 1;
         }
@@ -293,6 +322,7 @@ fn test_counter() {
     }
     candid::export_service!();
     let expected = r#"service : {
+  // Doc comment for inc
   inc : () -> ();
   read : () -> (nat64) query;
   set : (value : nat64) -> ();
diff --git a/rust/candid_derive/src/derive.rs b/rust/candid_derive/src/derive.rs
index 7f2838ff1..45bf5e1ff 100644
--- a/rust/candid_derive/src/derive.rs
+++ b/rust/candid_derive/src/derive.rs
@@ -1,4 +1,4 @@
-use super::{candid_path, get_lit_str, idl_hash};
+use super::{candid_path, get_comment_from_lines, get_comment_lines, get_lit_str, idl_hash};
 use proc_macro2::TokenStream;
 use quote::quote;
 use std::collections::BTreeSet;
@@ -12,12 +12,16 @@ pub(crate) fn derive_idl_type(
 ) -> TokenStream {
     let candid = candid_path(custom_candid_path);
     let name = input.ident;
+    let comment_lines = get_comment_lines(&input.attrs);
     let generics = add_trait_bounds(input.generics, custom_candid_path);
     let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
     let (ty_body, ser_body) = match input.data {
-        Data::Enum(ref data) => enum_from_ast(&name, &data.variants, custom_candid_path),
+        Data::Enum(ref data) => {
+            enum_from_ast(&name, &data.variants, custom_candid_path, &comment_lines)
+        }
         Data::Struct(ref data) => {
-            let (ty, idents, is_bytes, _) = struct_from_ast(&data.fields, custom_candid_path);
+            let (ty, idents, is_bytes, _) =
+                struct_from_ast(&data.fields, custom_candid_path, &comment_lines);
             (ty, serialize_struct(&idents, &is_bytes, custom_candid_path))
         }
         Data::Union(_) => unimplemented!("doesn't derive union type"),
@@ -49,6 +53,7 @@ struct Variant {
     members: Vec<Ident>,
     with_bytes: bool,
     style: Style,
+    comment_lines: Vec<String>,
 }
 enum Style {
     Struct,
@@ -93,12 +98,14 @@ fn enum_from_ast(
     name: &syn::Ident,
     variants: &Punctuated<syn::Variant, Token![,]>,
     custom_candid_path: &Option<TokenStream>,
+    comment_lines: &[String],
 ) -> (TokenStream, TokenStream) {
     let mut fs: Vec<_> = variants
         .iter()
         .map(|variant| {
             let id = variant.ident.clone();
             let attrs = get_attrs(&variant.attrs);
+            let variant_comment_lines = get_comment_lines(&variant.attrs);
             let (renamed_ident, hash) = match attrs.rename {
                 Some(ref rename) => (rename.clone(), idl_hash(rename)),
                 None => {
@@ -107,7 +114,7 @@ fn enum_from_ast(
                     (id, hash)
                 }
             };
-            let (ty, idents, _, style) = struct_from_ast(&variant.fields, custom_candid_path);
+            let (ty, idents, _, style) = struct_from_ast(&variant.fields, custom_candid_path, &[]);
             Variant {
                 real_ident: id,
                 renamed_ident,
@@ -116,6 +123,7 @@ fn enum_from_ast(
                 members: idents,
                 with_bytes: attrs.with_bytes,
                 style,
+                comment_lines: variant_comment_lines,
             }
         })
         .collect();
@@ -126,15 +134,20 @@ fn enum_from_ast(
     let id = fs.iter().map(|Variant { renamed_ident, .. }| renamed_ident);
     let ty = fs.iter().map(|Variant { ty, .. }| ty);
     let candid = candid_path(custom_candid_path);
+    let variant_comment = fs
+        .iter()
+        .map(|Variant { comment_lines, .. }| get_comment_from_lines(comment_lines, false));
+    let comment = get_comment_from_lines(comment_lines, true);
     let ty_gen = quote! {
-        #candid::types::TypeInner::Variant(
+        (#candid::types::TypeInner::Variant(
             vec![
                 #(#candid::types::Field {
                     id: #candid::types::Label::Named(#id.to_owned()).into(),
-                    ty: #ty }
+                    ty: #ty,
+                    comment: #variant_comment }
                 ),*
             ]
-        ).into()
+        ), #comment).into()
     };
 
     let id = fs.iter().map(|Variant { real_ident, .. }| {
@@ -195,13 +208,15 @@ fn serialize_struct(
 fn struct_from_ast(
     fields: &syn::Fields,
     custom_candid_path: &Option<TokenStream>,
+    comment_lines: &[String],
 ) -> (TokenStream, Vec<Ident>, Vec<bool>, Style) {
     let candid = candid_path(custom_candid_path);
+    let comment = get_comment_from_lines(comment_lines, true);
     match *fields {
         syn::Fields::Named(ref fields) => {
             let (fs, idents, is_bytes) = fields_from_ast(&fields.named, custom_candid_path);
             (
-                quote! { #candid::types::TypeInner::Record(#fs).into() },
+                quote! { (#candid::types::TypeInner::Record(#fs), #comment).into() },
                 idents,
                 is_bytes,
                 Style::Struct,
@@ -214,7 +229,7 @@ fn struct_from_ast(
                 (quote! { #newtype }, idents, is_bytes, Style::Tuple)
             } else {
                 (
-                    quote! { #candid::types::TypeInner::Record(#fs).into() },
+                    quote! { (#candid::types::TypeInner::Record(#fs), #comment).into() },
                     idents,
                     is_bytes,
                     Style::Tuple,
@@ -222,7 +237,7 @@ fn struct_from_ast(
             }
         }
         syn::Fields::Unit => (
-            quote! { #candid::types::TypeInner::Null.into() },
+            quote! { (#candid::types::TypeInner::Null, #comment).into() },
             Vec::new(),
             Vec::new(),
             Style::Unit,
@@ -262,6 +277,7 @@ struct Field {
     hash: u32,
     ty: TokenStream,
     with_bytes: bool,
+    comment_lines: Vec<String>,
 }
 
 fn get_serde_meta_items(attr: &syn::Attribute) -> Result<Vec<syn::Meta>, ()> {
@@ -334,6 +350,7 @@ fn fields_from_ast(
         .enumerate()
         .map(|(i, field)| {
             let attrs = get_attrs(&field.attrs);
+            let field_comment_lines = get_comment_lines(&field.attrs);
             let (real_ident, renamed_ident, hash) = match field.ident {
                 Some(ref ident) => {
                     let real_ident = Ident::Named(ident.clone());
@@ -357,6 +374,7 @@ fn fields_from_ast(
                 hash,
                 ty: derive_type(&field.ty, custom_candid_path),
                 with_bytes: attrs.with_bytes,
+                comment_lines: field_comment_lines,
             }
         })
         .collect();
@@ -377,11 +395,15 @@ fn fields_from_ast(
             Ident::Unnamed(ref i) => quote! { #candid::types::Label::Id(#i).into() },
         });
     let ty = fs.iter().map(|Field { ty, .. }| ty);
+    let comment = fs
+        .iter()
+        .map(|Field { comment_lines, .. }| get_comment_from_lines(comment_lines, false));
     let ty_gen = quote! {
         vec![
             #(#candid::types::Field {
                 id: #id,
-                ty: #ty }
+                ty: #ty,
+                comment: #comment }
             ),*
         ]
     };
diff --git a/rust/candid_derive/src/func.rs b/rust/candid_derive/src/func.rs
index 7c886563e..a8f1499ec 100644
--- a/rust/candid_derive/src/func.rs
+++ b/rust/candid_derive/src/func.rs
@@ -1,4 +1,4 @@
-use super::{candid_path, get_lit_str};
+use super::{candid_path, get_comment_from_lines, get_comment_lines, get_lit_str};
 use lazy_static::lazy_static;
 use proc_macro2::TokenStream;
 use quote::{quote, ToTokens};
@@ -6,15 +6,18 @@ use std::collections::BTreeMap;
 use std::sync::Mutex;
 use syn::{Error, ItemFn, Meta, Result, ReturnType, Signature, Type};
 
-type RawArgs = Vec<(Option<String>, String)>;
+type RawArg = (Option<String>, String);
+type RawArgs = Vec<RawArg>;
 type RawRets = Vec<String>;
 type ParsedArgs = Vec<(Option<String>, Type)>;
 type ParsedRets = Vec<Type>;
+type CommentLines = Vec<String>;
 
 struct Method {
     args: RawArgs,
     rets: RawRets,
     modes: String,
+    comment_lines: CommentLines,
 }
 
 // There is no official way to communicate information across proc macro invocations.
@@ -54,6 +57,7 @@ pub(crate) fn candid_method(attrs: Vec<Meta>, fun: ItemFn) -> Result<TokenStream
             "oneway function should have no return value",
         ));
     }
+    let comment_lines = get_comment_lines(&fun.attrs);
     if attrs.is_init {
         match (rets.len(), rets.first().map(|x| x.as_str())) {
             (0, None) | (1, Some("Self")) => {
@@ -69,7 +73,15 @@ pub(crate) fn candid_method(attrs: Vec<Meta>, fun: ItemFn) -> Result<TokenStream
             }
         }
     } else if let Some(map) = METHODS.lock().unwrap().as_mut() {
-        map.insert(name.clone(), Method { args, rets, modes });
+        map.insert(
+            name.clone(),
+            Method {
+                args,
+                rets,
+                modes,
+                comment_lines,
+            },
+        );
     }
     Ok(quote! { #fun })
 }
@@ -81,7 +93,7 @@ pub(crate) fn export_service(path: Option<TokenStream>) -> TokenStream {
             let res = opt_args.as_ref().map(|args| {
                 let args = args
                     .iter()
-                    .map(|t| generate_arg(quote! { init_args }, t))
+                    .map(|arg| generate_arg(quote! { init_args }, arg))
                     .collect::<Vec<_>>();
                 quote! {
                     let mut init_args: Vec<ArgType> = Vec::new();
@@ -93,33 +105,44 @@ pub(crate) fn export_service(path: Option<TokenStream>) -> TokenStream {
         } else {
             unreachable!();
         };
-        let gen_tys = meths.iter().map(|(name, Method { args, rets, modes })| {
-            let args = args
-                .iter()
-                .map(|t| generate_arg(quote! { args }, t))
-                .collect::<Vec<_>>();
-            let rets = rets
-                .iter()
-                .map(|t| generate_ret(quote! { rets }, t))
-                .collect::<Vec<_>>();
-            let modes = match modes.as_ref() {
-                "query" => quote! { vec![#candid::types::FuncMode::Query] },
-                "composite_query" => quote! { vec![#candid::types::FuncMode::CompositeQuery] },
-                "oneway" => quote! { vec![#candid::types::FuncMode::Oneway] },
-                "update" => quote! { vec![] },
-                _ => unreachable!(),
-            };
-            quote! {
-                {
-                    let mut args: Vec<ArgType> = Vec::new();
-                    #(#args)*
-                    let mut rets: Vec<Type> = Vec::new();
-                    #(#rets)*
-                    let func = Function { args, rets, modes: #modes };
-                    service.push((#name.to_string(), TypeInner::Func(func).into()));
+        let gen_tys = meths.iter().map(
+            |(
+                name,
+                Method {
+                    args,
+                    rets,
+                    modes,
+                    comment_lines,
+                },
+            )| {
+                let args = args
+                    .iter()
+                    .map(|arg| generate_arg(quote! { args }, arg))
+                    .collect::<Vec<_>>();
+                let rets = rets
+                    .iter()
+                    .map(|t| generate_ret(quote! { rets }, t))
+                    .collect::<Vec<_>>();
+                let modes = match modes.as_ref() {
+                    "query" => quote! { vec![#candid::types::FuncMode::Query] },
+                    "composite_query" => quote! { vec![#candid::types::FuncMode::CompositeQuery] },
+                    "oneway" => quote! { vec![#candid::types::FuncMode::Oneway] },
+                    "update" => quote! { vec![] },
+                    _ => unreachable!(),
+                };
+                let comment = get_comment_from_lines(comment_lines, true);
+                quote! {
+                    {
+                        let mut args: Vec<ArgType> = Vec::new();
+                        #(#args)*
+                        let mut rets: Vec<Type> = Vec::new();
+                        #(#rets)*
+                        let func = Function { args, rets, modes: #modes };
+                        service.push((#name.to_string(), (TypeInner::Func(func), #comment).into()));
+                    }
                 }
-            }
-        });
+            },
+        );
         let service = quote! {
             use #candid::types::{CandidType, Function, Type, ArgType, TypeInner};
             let mut service = Vec::<(String, Type)>::new();
@@ -152,7 +175,7 @@ pub(crate) fn export_service(path: Option<TokenStream>) -> TokenStream {
     }
 }
 
-fn generate_arg(name: TokenStream, (arg_name, ty): &(Option<String>, String)) -> TokenStream {
+fn generate_arg(name: TokenStream, (arg_name, ty): &RawArg) -> TokenStream {
     let arg_name = arg_name
         .as_ref()
         .map(|n| quote! { Some(#n.to_string()) })
diff --git a/rust/candid_derive/src/lib.rs b/rust/candid_derive/src/lib.rs
index eb26e4263..3ce32e5bd 100644
--- a/rust/candid_derive/src/lib.rs
+++ b/rust/candid_derive/src/lib.rs
@@ -61,6 +61,44 @@ pub(crate) fn get_lit_str(expr: &syn::Expr) -> std::result::Result<syn::LitStr,
     Err(())
 }
 
+pub(crate) fn get_comment_lines(attrs: &[syn::Attribute]) -> Vec<String> {
+    attrs
+        .iter()
+        .filter_map(|attr| match &attr.meta {
+            syn::Meta::NameValue(m) if m.path.is_ident("doc") => {
+                if let Ok(lit) = get_lit_str(&m.value) {
+                    Some(lit.value().trim().to_string())
+                } else {
+                    None
+                }
+            }
+            _ => None,
+        })
+        .collect()
+}
+
+pub(crate) fn get_comment_from_lines(
+    comment_lines: &[String],
+    as_slice: bool,
+) -> proc_macro2::TokenStream {
+    if comment_lines.is_empty() {
+        quote::quote! { None }
+    } else {
+        let comment_strings: Vec<proc_macro2::TokenStream> = comment_lines
+            .iter()
+            .map(|s| quote::quote! { #s.to_string() })
+            .collect();
+
+        let comment_lines = quote::quote! { vec![#(#comment_strings),*] };
+
+        if as_slice {
+            quote::quote! { Some(#comment_lines.as_slice()) }
+        } else {
+            quote::quote! { Some(std::rc::Rc::new(#comment_lines)) }
+        }
+    }
+}
+
 fn get_custom_candid_path(input: &syn::DeriveInput) -> Result<Option<proc_macro2::TokenStream>> {
     let candid_path_helper_attribute_option = input
         .attrs
diff --git a/rust/candid_parser/src/bindings/motoko.rs b/rust/candid_parser/src/bindings/motoko.rs
index f7ceb949a..e99dffb46 100644
--- a/rust/candid_parser/src/bindings/motoko.rs
+++ b/rust/candid_parser/src/bindings/motoko.rs
@@ -7,6 +7,8 @@ use candid::types::{ArgType, FuncMode};
 use candid::types::{Field, Function, Label, SharedLabel, Type, TypeEnv, TypeInner};
 use pretty::RcDoc;
 
+const DOC_COMMENT_LINE_PREFIX: &str = "/// ";
+
 // The definition of tuple is language specific.
 fn is_tuple(t: &Type) -> bool {
     match t.as_ref() {
@@ -159,10 +161,15 @@ fn pp_label(id: &SharedLabel) -> RcDoc {
 }
 
 fn pp_field(field: &Field) -> RcDoc {
-    pp_label(&field.id).append(" : ").append(pp_ty(&field.ty))
+    pp_comment(field.comment())
+        .append(pp_label(&field.id))
+        .append(" : ")
+        .append(pp_ty(&field.ty))
 }
 fn pp_variant(field: &Field) -> RcDoc {
-    let doc = str("#").append(pp_label(&field.id));
+    let doc = pp_comment(field.comment())
+        .append(str("#"))
+        .append(pp_label(&field.id));
     if *field.ty != TypeInner::Null {
         doc.append(" : ").append(pp_ty(&field.ty))
     } else {
@@ -240,8 +247,12 @@ fn pp_rets(args: &[Type]) -> RcDoc {
 
 fn pp_service(serv: &[(String, Type)]) -> RcDoc {
     let doc = concat(
-        serv.iter()
-            .map(|(id, func)| escape(id, true).append(" : ").append(pp_ty(func))),
+        serv.iter().map(|(id, func)| {
+            pp_comment(func.comment())
+                .append(escape(id, true))
+                .append(" : ")
+                .append(pp_ty(func))
+        }),
         ";",
     );
     kwd("actor").append(enclose_space("{", doc, "}"))
@@ -249,7 +260,8 @@ fn pp_service(serv: &[(String, Type)]) -> RcDoc {
 
 fn pp_defs(env: &TypeEnv) -> RcDoc {
     lines(env.0.iter().map(|(id, ty)| {
-        kwd("public type")
+        pp_comment(ty.comment())
+            .append(kwd("public type"))
             .append(escape(id, false))
             .append(" = ")
             .append(pp_ty(ty))
@@ -265,6 +277,20 @@ fn pp_actor(ty: &Type) -> RcDoc {
     }
 }
 
+fn pp_comment(comment_lines: Option<&[String]>) -> RcDoc {
+    let mut comment_doc = RcDoc::nil();
+    if let Some(comment_lines) = comment_lines {
+        for line in comment_lines {
+            comment_doc = comment_doc.append(
+                RcDoc::text(DOC_COMMENT_LINE_PREFIX)
+                    .append(line)
+                    .append(RcDoc::hardline()),
+            );
+        }
+    }
+    comment_doc
+}
+
 pub fn compile(env: &TypeEnv, actor: &Option<Type>) -> String {
     let header = r#"// This is a generated Motoko binding.
 // Please use `import service "ic:canister_id"` instead to call canisters on the IC if possible.
@@ -273,7 +299,9 @@ pub fn compile(env: &TypeEnv, actor: &Option<Type>) -> String {
         None => pp_defs(env),
         Some(actor) => {
             let defs = pp_defs(env);
-            let actor = kwd("public type Self =").append(pp_actor(actor));
+            let actor = pp_comment(actor.comment())
+                .append(kwd("public type Self ="))
+                .append(pp_actor(actor));
             defs.append(actor)
         }
     };
diff --git a/rust/candid_parser/src/bindings/rust.rs b/rust/candid_parser/src/bindings/rust.rs
index 4fa80e7e1..4ca4455d5 100644
--- a/rust/candid_parser/src/bindings/rust.rs
+++ b/rust/candid_parser/src/bindings/rust.rs
@@ -11,6 +11,8 @@ use serde::Serialize;
 use std::borrow::Cow;
 use std::collections::{BTreeMap, BTreeSet};
 
+const DOC_COMMENT_LINE_PREFIX: &str = "/// ";
+
 #[derive(Default, Deserialize, Clone, Debug)]
 pub struct BindingConfig {
     name: Option<String>,
@@ -92,15 +94,21 @@ pub(crate) fn is_tuple(fs: &[Field]) -> bool {
 }
 fn as_result(fs: &[Field]) -> Option<(&Type, &Type, bool)> {
     match fs {
-        [Field { id: ok, ty: t_ok }, Field { id: err, ty: t_err }]
-            if **ok == Label::Named("Ok".to_string())
-                && **err == Label::Named("Err".to_string()) =>
+        [Field {
+            id: ok, ty: t_ok, ..
+        }, Field {
+            id: err, ty: t_err, ..
+        }] if **ok == Label::Named("Ok".to_string())
+            && **err == Label::Named("Err".to_string()) =>
         {
             Some((t_ok, t_err, false))
         }
-        [Field { id: ok, ty: t_ok }, Field { id: err, ty: t_err }]
-            if **ok == Label::Named("ok".to_string())
-                && **err == Label::Named("err".to_string()) =>
+        [Field {
+            id: ok, ty: t_ok, ..
+        }, Field {
+            id: err, ty: t_err, ..
+        }] if **ok == Label::Named("ok".to_string())
+            && **err == Label::Named("err".to_string()) =>
         {
             Some((t_ok, t_err, true))
         }
@@ -152,6 +160,29 @@ fn pp_vis<'a>(vis: &Option<String>) -> RcDoc<'a> {
         None => RcDoc::text("pub "),
     }
 }
+fn pp_comment(comment_lines: Option<&[String]>) -> RcDoc {
+    let mut comment_doc = RcDoc::nil();
+    if let Some(comment_lines) = comment_lines {
+        for line in comment_lines {
+            comment_doc = comment_doc.append(
+                RcDoc::text(DOC_COMMENT_LINE_PREFIX)
+                    .append(line)
+                    .append(RcDoc::hardline()),
+            );
+        }
+    }
+    comment_doc
+}
+fn map_comment_lines(comment_lines: Option<&[String]>) -> CommentLines {
+    comment_lines
+        .map(|lines| {
+            lines
+                .iter()
+                .map(|l| format!("{DOC_COMMENT_LINE_PREFIX}{l}"))
+                .collect()
+        })
+        .unwrap_or_default()
+}
 
 impl<'a> State<'a> {
     fn generate_test(&mut self, src: &Type, use_type: &str) {
@@ -343,10 +374,11 @@ fn test_{test_name}() {{
     fn pp_record_field<'b>(&mut self, field: &'b Field, need_vis: bool, is_ref: bool) -> RcDoc<'b> {
         let lab = field.id.to_string();
         let old = self.state.push_state(&StateElem::Label(&lab));
-        let res = self
+        let f = self
             .pp_label(&field.id, false, need_vis)
             .append(kwd(":"))
             .append(self.pp_ty(&field.ty, is_ref));
+        let res = pp_comment(field.comment()).append(f);
         self.state.pop_state(old, StateElem::Label(&lab));
         res
     }
@@ -375,7 +407,7 @@ fn test_{test_name}() {{
     fn pp_variant_field<'b>(&mut self, field: &'b Field) -> RcDoc<'b> {
         let lab = field.id.to_string();
         let old = self.state.push_state(&StateElem::Label(&lab));
-        let res = match field.ty.as_ref() {
+        let f = match field.ty.as_ref() {
             TypeInner::Null => self.pp_label(&field.id, true, false),
             TypeInner::Record(fs) => self
                 .pp_label(&field.id, true, false)
@@ -386,6 +418,7 @@ fn test_{test_name}() {{
                 ")",
             )),
         };
+        let res = pp_comment(field.comment()).append(f);
         self.state.pop_state(old, StateElem::Label(&lab));
         res
     }
@@ -488,8 +521,9 @@ fn test_{test_name}() {{
                     }
                 }
             };
+            let line_with_comment = pp_comment(ty.comment()).append(line);
             self.state.pop_state(old, StateElem::Label(id));
-            res.push(line)
+            res.push(line_with_comment)
         }
         lines(res.into_iter())
     }
@@ -559,7 +593,12 @@ fn test_{test_name}() {{
         self.state.pop_state(old, lab);
         res
     }
-    fn pp_function(&mut self, id: &str, func: &Function) -> Method {
+    fn pp_function(
+        &mut self,
+        id: &str,
+        func: &Function,
+        comment_lines: Option<&[String]>,
+    ) -> Method {
         use candid::types::internal::FuncMode;
         let old = self.state.push_state(&StateElem::Label(id));
         let name = self
@@ -619,11 +658,12 @@ fn test_{test_name}() {{
                 .map(|x| x.pretty(LINE_WIDTH).to_string())
                 .collect(),
             mode,
+            comment_lines: map_comment_lines(comment_lines),
         };
         self.state.pop_state(old, StateElem::Label(id));
         res
     }
-    fn pp_actor(&mut self, actor: &Type) -> (Vec<Method>, Option<Vec<(String, String)>>) {
+    fn pp_actor(&mut self, actor: &Type) -> (Methods, InitArgs, CommentLines) {
         let actor = self.state.env.trace_type(actor).unwrap();
         let init = if let TypeInner::Class(args, _) = actor.as_ref() {
             let old = self.state.push_state(&StateElem::Label("init"));
@@ -653,27 +693,35 @@ fn test_{test_name}() {{
         let serv = self.state.env.as_service(&actor).unwrap();
         let mut res = Vec::new();
         for (id, func) in serv.iter() {
+            let comment = func.comment();
             let func = self.state.env.as_func(func).unwrap();
-            res.push(self.pp_function(id, func));
+            res.push(self.pp_function(id, func, comment));
         }
-        (res, init)
+        (res, init, map_comment_lines(actor.comment()))
     }
 }
 #[derive(Serialize, Debug)]
 pub struct Output {
     pub type_defs: String,
-    pub methods: Vec<Method>,
-    pub init_args: Option<Vec<(String, String)>>,
+    pub methods: Methods,
+    pub init_args: InitArgs,
+    pub actor_comment_lines: CommentLines,
     pub tests: String,
 }
 #[derive(Serialize, Debug)]
 pub struct Method {
     pub name: String,
     pub original_name: String,
-    pub args: Vec<(String, String)>,
+    pub args: Args,
     pub rets: Vec<String>,
     pub mode: String,
+    pub comment_lines: CommentLines,
 }
+type Methods = Vec<Method>;
+type Args = Vec<(String, String)>;
+type InitArgs = Option<Args>;
+type CommentLines = Vec<String>;
+
 pub fn emit_bindgen(tree: &Config, env: &TypeEnv, actor: &Option<Type>) -> (Output, Vec<String>) {
     let mut state = NominalState {
         state: crate::configs::State::new(&tree.0, env),
@@ -693,10 +741,10 @@ pub fn emit_bindgen(tree: &Config, env: &TypeEnv, actor: &Option<Type>) -> (Outp
     };
     state.state.stats = old_stats;
     let defs = state.pp_defs(&def_list);
-    let (methods, init_args) = if let Some(actor) = &actor {
+    let (methods, init_args, actor_comment_lines) = if let Some(actor) = &actor {
         state.pp_actor(actor)
     } else {
-        (Vec::new(), None)
+        (Vec::new(), None, Vec::new())
     };
     let tests = state.tests.into_values().collect::<Vec<_>>().join("\n");
     let unused = state.state.report_unused();
@@ -705,6 +753,7 @@ pub fn emit_bindgen(tree: &Config, env: &TypeEnv, actor: &Option<Type>) -> (Outp
             type_defs: defs.pretty(LINE_WIDTH).to_string(),
             methods,
             init_args,
+            actor_comment_lines,
             tests,
         },
         unused,
@@ -717,8 +766,9 @@ pub fn output_handlebar(output: Output, config: ExternalConfig, template: &str)
         #[serde(flatten)]
         external: BTreeMap<String, String>,
         type_defs: String,
-        methods: Vec<Method>,
-        init_args: Option<Vec<(String, String)>>,
+        methods: Methods,
+        init_args: InitArgs,
+        actor_comment_lines: CommentLines,
         tests: String,
     }
     let data = HBOutput {
@@ -726,6 +776,7 @@ pub fn output_handlebar(output: Output, config: ExternalConfig, template: &str)
         methods: output.methods,
         external: config.0,
         init_args: output.init_args,
+        actor_comment_lines: output.actor_comment_lines,
         tests: output.tests,
     };
     hbs.render_template(template, &data).unwrap()
@@ -820,7 +871,7 @@ impl NominalState<'_> {
         } else {
             Some(self.state.push_state(&elem))
         };
-        let res = match t.as_ref() {
+        let inner = match t.as_ref() {
             TypeInner::Opt(ty) => {
                 path.push(TypePath::Opt);
                 let ty = self.nominalize(env, path, ty);
@@ -841,7 +892,7 @@ impl NominalState<'_> {
                 {
                     let fs: Vec<_> = fs
                         .iter()
-                        .map(|Field { id, ty }| {
+                        .map(|Field { id, ty, comment }| {
                             let lab = id.to_string();
                             let elem = StateElem::Label(&lab);
                             let old = self.state.push_state(&elem);
@@ -849,7 +900,11 @@ impl NominalState<'_> {
                             let ty = self.nominalize(env, path, ty);
                             path.pop();
                             self.state.pop_state(old, elem);
-                            Field { id: id.clone(), ty }
+                            Field {
+                                id: id.clone(),
+                                ty,
+                                comment: comment.clone(),
+                            }
                         })
                         .collect();
                     TypeInner::Record(fs)
@@ -864,7 +919,7 @@ impl NominalState<'_> {
                     let ty = self.nominalize(
                         env,
                         &mut vec![TypePath::Id(new_var.clone())],
-                        &TypeInner::Record(fs.to_vec()).into(),
+                        &(TypeInner::Record(fs.to_vec()), None).into(),
                     );
                     env.0.insert(new_var.clone(), ty);
                     TypeInner::Var(new_var)
@@ -875,7 +930,7 @@ impl NominalState<'_> {
                 if matches!(path.last(), None | Some(TypePath::Id(_))) || is_result {
                     let fs: Vec<_> = fs
                         .iter()
-                        .map(|Field { id, ty }| {
+                        .map(|Field { id, ty, comment }| {
                             let lab = id.to_string();
                             let old = self.state.push_state(&StateElem::Label(&lab));
                             if is_result {
@@ -887,7 +942,11 @@ impl NominalState<'_> {
                             let ty = self.nominalize(env, path, ty);
                             path.pop();
                             self.state.pop_state(old, StateElem::Label(&lab));
-                            Field { id: id.clone(), ty }
+                            Field {
+                                id: id.clone(),
+                                ty,
+                                comment: comment.clone(),
+                            }
                         })
                         .collect();
                     TypeInner::Variant(fs)
@@ -902,7 +961,7 @@ impl NominalState<'_> {
                     let ty = self.nominalize(
                         env,
                         &mut vec![TypePath::Id(new_var.clone())],
-                        &TypeInner::Variant(fs.to_vec()).into(),
+                        &(TypeInner::Variant(fs.to_vec()), None).into(),
                     );
                     env.0.insert(new_var.clone(), ty);
                     TypeInner::Var(new_var)
@@ -967,7 +1026,7 @@ impl NominalState<'_> {
                     let ty = self.nominalize(
                         env,
                         &mut vec![TypePath::Id(new_var.clone())],
-                        &TypeInner::Func(func.clone()).into(),
+                        &(TypeInner::Func(func.clone()), None).into(),
                     );
                     env.0.insert(new_var.clone(), ty);
                     TypeInner::Var(new_var)
@@ -998,7 +1057,7 @@ impl NominalState<'_> {
                     let ty = self.nominalize(
                         env,
                         &mut vec![TypePath::Id(new_var.clone())],
-                        &TypeInner::Service(serv.clone()).into(),
+                        &(TypeInner::Service(serv.clone()), None).into(),
                     );
                     env.0.insert(new_var.clone(), ty);
                     TypeInner::Var(new_var)
@@ -1022,8 +1081,8 @@ impl NominalState<'_> {
                 self.nominalize(env, path, ty),
             ),
             t => t.clone(),
-        }
-        .into();
+        };
+        let res = (inner, t.comment()).into();
         if let Some(old) = old {
             self.state.pop_state(old, elem);
         }
diff --git a/rust/candid_parser/src/bindings/rust_agent.hbs b/rust/candid_parser/src/bindings/rust_agent.hbs
index 4e0526254..9d0f3b3b1 100644
--- a/rust/candid_parser/src/bindings/rust_agent.hbs
+++ b/rust/candid_parser/src/bindings/rust_agent.hbs
@@ -6,9 +6,15 @@ type Result<T> = std::result::Result<T, ic_agent::AgentError>;
 
 {{type_defs}}
 {{#if methods}}
+{{#each actor_comment_lines}}
+{{this}}
+{{/each}}
 pub struct {{PascalCase service_name}}<'a>(pub Principal, pub &'a ic_agent::Agent);
 impl<'a> {{PascalCase service_name}}<'a> {
   {{#each methods}}
+  {{#each this.comment_lines}}
+  {{this}}
+  {{/each}}
   pub async fn {{this.name}}(&self{{#each this.args}}, {{this.0}}: &{{this.1}}{{/each}}) -> Result<{{vec_to_arity this.rets}}> {
     let args = Encode!({{#each this.args}}&{{this.0}}{{#unless @last}},{{/unless}}{{/each}})?;
     let bytes = self.1.{{#if (eq this.mode "update")}}update{{else}}query{{/if}}(&self.0, "{{escape_debug this.original_name}}").with_arg(args).{{#if (eq this.mode "update")}}call_and_wait{{else}}call{{/if}}().await?;
@@ -17,7 +23,8 @@ impl<'a> {{PascalCase service_name}}<'a> {
   {{/each}}
 }
 {{#if canister_id}}
-pub const CANISTER_ID : Principal = Principal::from_slice(&[{{principal_slice canister_id}}]); // {{canister_id}}
+/// Canister ID: `{{canister_id}}`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[{{principal_slice canister_id}}]);
 {{/if}}
 {{/if}}
 {{#if tests}}
diff --git a/rust/candid_parser/src/bindings/rust_call.hbs b/rust/candid_parser/src/bindings/rust_call.hbs
index 788fc0db3..869c103a1 100644
--- a/rust/candid_parser/src/bindings/rust_call.hbs
+++ b/rust/candid_parser/src/bindings/rust_call.hbs
@@ -6,16 +6,26 @@ use ic_cdk::api::call::CallResult as Result;
 
 {{type_defs}}
 {{#if methods}}
+{{#each actor_comment_lines}}
+{{this}}
+{{/each}}
 pub struct {{PascalCase service_name}}(pub Principal);
 impl {{PascalCase service_name}} {
   {{#each methods}}
+  {{#each this.comment_lines}}
+  {{this}}
+  {{/each}}
   pub async fn {{this.name}}(&self{{#each this.args}}, {{this.0}}: &{{this.1}}{{/each}}) -> Result<({{#each this.rets}}{{this}},{{/each}})> {
     ic_cdk::call(self.0, "{{escape_debug this.original_name}}", ({{#each this.args}}{{this.0}},{{/each}})).await
   }
   {{/each}}
 }
 {{#if canister_id}}
-pub const CANISTER_ID : Principal = Principal::from_slice(&[{{principal_slice canister_id}}]); // {{canister_id}}
+/// Canister ID: `{{canister_id}}`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[{{principal_slice canister_id}}]);
+{{#each actor_comment_lines}}
+{{this}}
+{{/each}}
 pub const {{snake_case service_name}} : {{PascalCase service_name}} = {{PascalCase service_name}}(CANISTER_ID);
 {{/if}}
 {{/if}}
diff --git a/rust/candid_parser/src/bindings/rust_stub.hbs b/rust/candid_parser/src/bindings/rust_stub.hbs
index a0cf2c4cd..0c27e7e77 100644
--- a/rust/candid_parser/src/bindings/rust_stub.hbs
+++ b/rust/candid_parser/src/bindings/rust_stub.hbs
@@ -11,6 +11,9 @@ fn init({{#each init_args}}{{#if (not @first)}}, {{/if}}{{this.0}}: {{this.1}}{{
 }
 {{/if}}
 {{#each methods}}
+{{#each this.comment_lines}}
+{{this}}
+{{/each}}
 #[ic_cdk::{{cdk_attribute this.mode this.name this.original_name}}]
 fn {{this.name}}({{#each this.args}}{{#if (not @first)}}, {{/if}}{{this.0}}: {{this.1}}{{/each}}) -> {{vec_to_arity this.rets}} {
   unimplemented!()
diff --git a/rust/candid_parser/src/bindings/typescript.rs b/rust/candid_parser/src/bindings/typescript.rs
index 5a4460bf2..c7a72ee8e 100644
--- a/rust/candid_parser/src/bindings/typescript.rs
+++ b/rust/candid_parser/src/bindings/typescript.rs
@@ -3,6 +3,10 @@ use candid::pretty::utils::*;
 use candid::types::{Field, Function, Label, SharedLabel, Type, TypeEnv, TypeInner};
 use pretty::RcDoc;
 
+const DOC_COMMENT_PREFIX: &str = "/**";
+const DOC_COMMENT_LINE_PREFIX: &str = " * ";
+const DOC_COMMENT_SUFFIX: &str = " */";
+
 fn pp_ty<'a>(env: &'a TypeEnv, ty: &'a Type, is_ref: bool) -> RcDoc<'a> {
     use TypeInner::*;
     match ty.as_ref() {
@@ -103,7 +107,8 @@ fn pp_label(id: &SharedLabel) -> RcDoc {
 }
 
 fn pp_field<'a>(env: &'a TypeEnv, field: &'a Field, is_ref: bool) -> RcDoc<'a> {
-    pp_label(&field.id)
+    pp_comment(field.comment())
+        .append(pp_label(&field.id))
         .append(kwd(":"))
         .append(pp_ty(env, &field.ty, is_ref))
 }
@@ -130,11 +135,14 @@ fn pp_function<'a>(env: &'a TypeEnv, func: &'a Function) -> RcDoc<'a> {
 fn pp_service<'a>(env: &'a TypeEnv, serv: &'a [(String, Type)]) -> RcDoc<'a> {
     let doc = concat(
         serv.iter().map(|(id, func)| {
-            let func = match func.as_ref() {
-                TypeInner::Func(ref func) => pp_function(env, func),
+            let f = match func.as_ref() {
+                TypeInner::Func(ref inner) => pp_function(env, inner),
                 _ => pp_ty(env, func, false),
             };
-            quote_ident(id).append(kwd(":")).append(func)
+            pp_comment(func.comment())
+                .append(quote_ident(id))
+                .append(kwd(":"))
+                .append(f)
         }),
         ",",
     );
@@ -144,7 +152,7 @@ fn pp_service<'a>(env: &'a TypeEnv, serv: &'a [(String, Type)]) -> RcDoc<'a> {
 fn pp_defs<'a>(env: &'a TypeEnv, def_list: &'a [&'a str]) -> RcDoc<'a> {
     lines(def_list.iter().map(|id| {
         let ty = env.find_type(id).unwrap();
-        let export = match ty.as_ref() {
+        let doc = match ty.as_ref() {
             TypeInner::Record(_) if !ty.is_tuple() => kwd("export interface")
                 .append(ident(id))
                 .append(" ")
@@ -156,7 +164,7 @@ fn pp_defs<'a>(env: &'a TypeEnv, def_list: &'a [&'a str]) -> RcDoc<'a> {
             TypeInner::Func(ref func) => kwd("export type")
                 .append(ident(id))
                 .append(" = ")
-                .append(pp_function(env, func))
+                .append(pp_function(env, func)) // the comment is already added at the end of this match block
                 .append(";"),
             _ => kwd("export type")
                 .append(ident(id))
@@ -164,7 +172,7 @@ fn pp_defs<'a>(env: &'a TypeEnv, def_list: &'a [&'a str]) -> RcDoc<'a> {
                 .append(pp_ty(env, ty, false))
                 .append(";"),
         };
-        export
+        pp_comment(ty.comment()).append(doc)
     }))
 }
 
@@ -181,6 +189,29 @@ fn pp_actor<'a>(env: &'a TypeEnv, ty: &'a Type) -> RcDoc<'a> {
     }
 }
 
+fn pp_comment(comment_lines: Option<&[String]>) -> RcDoc {
+    let mut comment_doc = RcDoc::nil();
+    let mut is_empty = true;
+    if let Some(comment_lines) = comment_lines {
+        is_empty = comment_lines.is_empty();
+        for line in comment_lines {
+            comment_doc = comment_doc.append(
+                RcDoc::text(DOC_COMMENT_LINE_PREFIX)
+                    .append(line)
+                    .append(RcDoc::hardline()),
+            );
+        }
+    }
+    if !is_empty {
+        comment_doc = RcDoc::text(DOC_COMMENT_PREFIX)
+            .append(RcDoc::hardline())
+            .append(comment_doc)
+            .append(RcDoc::text(DOC_COMMENT_SUFFIX))
+            .append(RcDoc::hardline());
+    }
+    comment_doc
+}
+
 pub fn compile(env: &TypeEnv, actor: &Option<Type>) -> String {
     let header = r#"import type { Principal } from '@dfinity/principal';
 import type { ActorMethod } from '@dfinity/agent';
@@ -190,7 +221,8 @@ import type { IDL } from '@dfinity/candid';
     let defs = pp_defs(env, &def_list);
     let actor = match actor {
         None => RcDoc::nil(),
-        Some(actor) => pp_actor(env, actor)
+        Some(actor) => pp_comment(actor.comment())
+            .append(pp_actor(env, actor))
             .append(RcDoc::line())
             .append("export declare const idlFactory: IDL.InterfaceFactory;")
             .append(RcDoc::line())
diff --git a/rust/candid_parser/src/grammar.lalrpop b/rust/candid_parser/src/grammar.lalrpop
index 3a3f3bb05..d1579e0b2 100644
--- a/rust/candid_parser/src/grammar.lalrpop
+++ b/rust/candid_parser/src/grammar.lalrpop
@@ -1,4 +1,4 @@
-use super::types::{IDLType, PrimType, TypeField, FuncType, Binding, Dec, IDLProg, IDLTypes, IDLInitArgs, IDLArgType};
+use super::types::{IDLType, PrimType, TypeField, FuncType, Binding, ActorBinding, Dec, IDLProg, IDLTypes, IDLInitArgs, IDLArgType, Comment};
 use super::test::{Assert, Input, Test};
 use super::token::{Token, error, error2, LexicalError, Span};
 use candid::{Principal, types::Label};
@@ -46,6 +46,8 @@ extern {
         ";" => Token::Semi,
         ":" => Token::Colon,
         "->" => Token::Arrow,
+        "line_comment" => Token::LineComment(<Vec<String>>),
+        "\n" => Token::Newline,
     }
 }
 
@@ -174,7 +176,7 @@ pub Typ: IDLType = {
               Label::Unnamed(_) => { id = id + 1; Label::Unnamed(id - 1) },
               ref l => { id = l.get_id() + 1; l.clone() },
           };
-          TypeField { label, typ: f.typ.clone() }
+          TypeField { label, typ: f.typ.clone(), comment: f.comment.clone() }
         }).collect();
         fs.sort_unstable_by_key(|TypeField { label, .. }| label.get_id());
         check_unique(fs.iter().map(|f| &f.label)).map_err(|e| error2(e, span))?;
@@ -202,19 +204,19 @@ PrimTyp: IDLType = {
 }
 
 FieldTyp: TypeField = {
-    <n:FieldId> ":" <t:Typ> =>? Ok(TypeField { label: Label::Id(n), typ: t }),
-    <n:Name> ":" <t:Typ> => TypeField { label: Label::Named(n), typ: t },
+    <comment:Comment?> <n:FieldId> ":" <t:Typ> =>? Ok(TypeField { label: Label::Id(n), typ: t, comment }),
+    <comment:Comment?> <n:Name> ":" <t:Typ> => TypeField { label: Label::Named(n), typ: t, comment },
 }
 
 RecordFieldTyp: TypeField = {
     FieldTyp => <>,
-    Typ => TypeField { label: Label::Unnamed(0), typ: <> },
+    Typ => TypeField { label: Label::Unnamed(0), typ: <>, comment: None },
 }
 
 VariantFieldTyp: TypeField = {
     FieldTyp => <>,
-    Name => TypeField { label: Label::Named(<>), typ: IDLType::PrimT(PrimType::Null) },
-    FieldId =>? Ok(TypeField { label: Label::Id(<>), typ: IDLType::PrimT(PrimType::Null) }),
+    <comment:Comment?> <n:Name> => TypeField { label: Label::Named(n), typ: IDLType::PrimT(PrimType::Null), comment },
+    <comment:Comment?> <n:FieldId> =>? Ok(TypeField { label: Label::Id(n), typ: IDLType::PrimT(PrimType::Null), comment }),
 }
 
 ArgTupTyp: Vec<IDLArgType> = "(" <SepBy<ArgTyp, ",">> ")" =>? {
@@ -253,15 +255,15 @@ ActorTyp: Vec<Binding> = {
 }
 
 MethTyp: Binding = {
-    <n:Name> ":" <f:FuncTyp> => Binding { id: n, typ: IDLType::FuncT(f) },
-    <n:Name> ":" <id:"id"> => Binding { id: n, typ: IDLType::VarT(id) },
+    <comment:Comment?> <n:Name> ":" <f:FuncTyp> => Binding { id: n, typ: IDLType::FuncT(f), comment },
+    <comment:Comment?> <n:Name> ":" <id:"id"> => Binding { id: n, typ: IDLType::VarT(id), comment },
 }
 
 // Type declarations
 Def: Dec = {
-    "type" <id:"id"> "=" <t:Typ> => Dec::TypD(Binding { id: id, typ: t }),
-    "import" <Text> => Dec::ImportType(<>),
-    "import" "service" <Text> => Dec::ImportServ(<>),
+    <comment:Comment?> "type" <id:"id"> "=" <typ:Typ> => Dec::TypD(Binding { id, typ, comment }),
+    Comment? "import" <Text> => Dec::ImportType(<>),
+    Comment? "import" "service" <Text> => Dec::ImportServ(<>),
 }
 
 Actor: IDLType = {
@@ -269,9 +271,9 @@ Actor: IDLType = {
     "id" => IDLType::VarT(<>),
 }
 
-MainActor: IDLType = {
-    "service" "id"? ":" <t:Actor> ";"? => <>,
-    "service" "id"? ":" <args:ArgTupTyp> "->" <t:Actor> ";"? => IDLType::ClassT(args, Box::new(t)),
+MainActor: ActorBinding = {
+    <comment:Comment?> "service" "id"? ":" <typ:Actor> ";"? => ActorBinding { typ, comment },
+    <comment:Comment?> "service" "id"? ":" <args:ArgTupTyp> "->" <t:Actor> ";"? => ActorBinding { typ: IDLType::ClassT(args, Box::new(t)), comment },
 }
 
 pub IDLProg: IDLProg = {
@@ -289,7 +291,7 @@ Input: Input = {
     Bytes => Input::Blob(<>),
 }
 
-Assert: Assert = <id:Sp<"id">> <assert:Assertion> =>? {
+Assert: Assert = Comment? <id:Sp<"id">> <assert:Assertion> =>? {
     if id.0 != "assert" {
         Err(error2("not an assert", id.1))
     } else { Ok(assert) }
@@ -312,6 +314,10 @@ Name: String = {
     Text => <>,
 }
 
+Comment: Comment = {
+    "line_comment" => Comment { lines: <> },
+}
+
 // Also allows trailing separator
 #[inline]
 SepBy<T, S>: Vec<T> = {
diff --git a/rust/candid_parser/src/random.rs b/rust/candid_parser/src/random.rs
index 8a38e586d..cd22f2a64 100644
--- a/rust/candid_parser/src/random.rs
+++ b/rust/candid_parser/src/random.rs
@@ -215,7 +215,7 @@ impl RandState<'_> {
             }
             TypeInner::Record(fs) => {
                 let mut res = Vec::new();
-                for Field { id, ty } in fs.iter() {
+                for Field { id, ty, .. } in fs.iter() {
                     let lab_str = id.to_string();
                     let elem = StateElem::Label(&lab_str);
                     let old_config = self.0.push_state(&elem);
@@ -243,7 +243,7 @@ impl RandState<'_> {
                     choices.collect()
                 };
                 let idx = arbitrary_variant(u, &sizes)?;
-                let Field { id, ty } = &fs[idx];
+                let Field { id, ty, .. } = &fs[idx];
                 let lab_str = id.to_string();
                 let elem = StateElem::Label(&lab_str);
                 let old_config = self.0.push_state(&elem);
diff --git a/rust/candid_parser/src/token.rs b/rust/candid_parser/src/token.rs
index db7ae2d61..dc655081b 100644
--- a/rust/candid_parser/src/token.rs
+++ b/rust/candid_parser/src/token.rs
@@ -2,11 +2,14 @@ use lalrpop_util::ParseError;
 use logos::{Lexer, Logos};
 
 #[derive(Logos, Debug, Clone, PartialEq, Eq, Ord, PartialOrd)]
-#[logos(skip r"[ \t\r\n]+")]
-#[logos(skip r"//[^\n]*")] // line comment
+#[logos(skip r"[ \t\r]+")]
+#[logos(skip r"([ \t]*//[^\n]*\n)+\n")] // ignore line comments that are followed by an empty line
 pub enum Token {
     #[token("/*")]
     StartComment,
+    // catch line comments at any indentation level, thanks to the `[ \t]*` prefix
+    #[regex(r"([ \t]*//[^\n]*\n)+", parse_comment_lines)]
+    LineComment(Vec<String>),
     #[token("=")]
     Equals,
     #[token("(")]
@@ -78,6 +81,8 @@ pub enum Token {
     Float(String),
     #[regex("true|false", |lex| lex.slice().parse().map_err(|_| ()))]
     Boolean(bool),
+    #[token("\n")]
+    Newline,
 }
 
 #[derive(Logos, Debug, Clone, PartialEq, Eq)]
@@ -118,6 +123,14 @@ fn parse_number(lex: &mut Lexer<Token>) -> String {
     }
 }
 
+fn parse_comment_lines(lex: &mut Lexer<Token>) -> Vec<String> {
+    lex.slice()
+        .lines()
+        .map(|s| s.trim().trim_start_matches("//").trim().to_string())
+        .filter(|s| !s.is_empty())
+        .collect()
+}
+
 pub struct Tokenizer<'input> {
     lex: Lexer<'input, Token>,
 }
@@ -203,6 +216,32 @@ impl Iterator for Tokenizer<'_> {
                 self.lex = lex.morph::<Token>();
                 self.next()
             }
+            Ok(Token::LineComment(mut lines)) => {
+                let span = self.lex.span();
+                let source = self.lex.source();
+
+                // Check the char before the span: if it's NOT a newline, it means that
+                // the comment is at the end of a line and therefore it must be ignored.
+                // If it's at the start of the source (prev_char_index == 0), we don't have to check anything.
+                let prev_char_index = span.start.saturating_sub(1);
+                if prev_char_index > 0 {
+                    let is_end_of_line_comment = source
+                        .chars()
+                        .nth(prev_char_index)
+                        .map(|c| c != '\n')
+                        .unwrap_or(false);
+
+                    if is_end_of_line_comment {
+                        lines.remove(0);
+                    }
+                }
+
+                // Ignore the comment if it's empty
+                if lines.is_empty() {
+                    return self.next();
+                }
+                Some(Ok((span.start, Token::LineComment(lines), span.end)))
+            }
             Ok(Token::StartString) => {
                 let mut result = String::new();
                 let mut lex = self.lex.to_owned().morph::<Text>();
@@ -278,6 +317,7 @@ impl Iterator for Tokenizer<'_> {
                 self.lex = lex.morph::<Token>();
                 Some(Ok((span.start, Token::Text(result), self.lex.span().end)))
             }
+            Ok(Token::Newline) => self.next(),
             Ok(token) => Some(Ok((span.start, token, span.end))),
         }
     }
diff --git a/rust/candid_parser/src/types.rs b/rust/candid_parser/src/types.rs
index 91ed6efdb..0d91a614c 100644
--- a/rust/candid_parser/src/types.rs
+++ b/rust/candid_parser/src/types.rs
@@ -91,10 +91,28 @@ impl IDLArgType {
     }
 }
 
+#[derive(Debug, Clone)]
+pub struct Comment {
+    pub lines: Vec<String>,
+}
+
+impl Comment {
+    pub fn lines(&self) -> &[String] {
+        &self.lines
+    }
+}
+
 #[derive(Debug, Clone)]
 pub struct TypeField {
     pub label: Label,
     pub typ: IDLType,
+    pub comment: Option<Comment>,
+}
+
+impl TypeField {
+    pub fn comment(&self) -> Option<&[String]> {
+        self.comment.as_ref().map(|c| c.lines())
+    }
 }
 
 #[derive(Debug)]
@@ -108,12 +126,19 @@ pub enum Dec {
 pub struct Binding {
     pub id: String,
     pub typ: IDLType,
+    pub comment: Option<Comment>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ActorBinding {
+    pub typ: IDLType,
+    pub comment: Option<Comment>,
 }
 
 #[derive(Debug)]
 pub struct IDLProg {
     pub decs: Vec<Dec>,
-    pub actor: Option<IDLType>,
+    pub actor: Option<ActorBinding>,
 }
 
 #[derive(Debug)]
diff --git a/rust/candid_parser/src/typing.rs b/rust/candid_parser/src/typing.rs
index 3cc20367f..031a79e5b 100644
--- a/rust/candid_parser/src/typing.rs
+++ b/rust/candid_parser/src/typing.rs
@@ -16,10 +16,10 @@ pub fn ast_to_type(env: &TypeEnv, ast: &super::types::IDLType) -> Result<Type> {
         te: &mut env.clone(),
         pre: false,
     };
-    check_type(&env, ast)
+    check_type(&env, ast, None)
 }
 
-fn check_prim(prim: &PrimType) -> Type {
+fn check_prim(prim: &PrimType) -> TypeInner {
     match prim {
         PrimType::Nat => TypeInner::Nat,
         PrimType::Nat8 => TypeInner::Nat8,
@@ -39,33 +39,32 @@ fn check_prim(prim: &PrimType) -> Type {
         PrimType::Reserved => TypeInner::Reserved,
         PrimType::Empty => TypeInner::Empty,
     }
-    .into()
 }
 
-pub fn check_type(env: &Env, t: &IDLType) -> Result<Type> {
-    match t {
+pub fn check_type(env: &Env, t: &IDLType, comment_lines: Option<&[String]>) -> Result<Type> {
+    let inner = match t {
         IDLType::PrimT(prim) => Ok(check_prim(prim)),
         IDLType::VarT(id) => {
             env.te.find_type(id)?;
-            Ok(TypeInner::Var(id.to_string()).into())
+            Ok(TypeInner::Var(id.to_string()))
         }
         IDLType::OptT(t) => {
-            let t = check_type(env, t)?;
-            Ok(TypeInner::Opt(t).into())
+            let t = check_type(env, t, comment_lines)?;
+            Ok(TypeInner::Opt(t))
         }
         IDLType::VecT(t) => {
-            let t = check_type(env, t)?;
-            Ok(TypeInner::Vec(t).into())
+            let t = check_type(env, t, comment_lines)?;
+            Ok(TypeInner::Vec(t))
         }
         IDLType::RecordT(fs) => {
             let fs = check_fields(env, fs)?;
-            Ok(TypeInner::Record(fs).into())
+            Ok(TypeInner::Record(fs))
         }
         IDLType::VariantT(fs) => {
             let fs = check_fields(env, fs)?;
-            Ok(TypeInner::Variant(fs).into())
+            Ok(TypeInner::Variant(fs))
         }
-        IDLType::PrincipalT => Ok(TypeInner::Principal.into()),
+        IDLType::PrincipalT => Ok(TypeInner::Principal),
         IDLType::FuncT(func) => {
             let mut t1 = Vec::new();
             for arg in func.args.iter() {
@@ -73,7 +72,7 @@ pub fn check_type(env: &Env, t: &IDLType) -> Result<Type> {
             }
             let mut t2 = Vec::new();
             for t in func.rets.iter() {
-                t2.push(check_type(env, t)?);
+                t2.push(check_type(env, t, comment_lines)?);
             }
             if func.modes.len() > 1 {
                 return Err(Error::msg("cannot have more than one mode"));
@@ -89,20 +88,21 @@ pub fn check_type(env: &Env, t: &IDLType) -> Result<Type> {
                 args: t1,
                 rets: t2,
             };
-            Ok(TypeInner::Func(f).into())
+            Ok(TypeInner::Func(f))
         }
         IDLType::ServT(ms) => {
             let ms = check_meths(env, ms)?;
-            Ok(TypeInner::Service(ms).into())
+            Ok(TypeInner::Service(ms))
         }
         IDLType::ClassT(_, _) => Err(Error::msg("service constructor not supported")),
-    }
+    }?;
+    Ok((inner, comment_lines).into())
 }
 
 fn check_arg(env: &Env, arg: &IDLArgType) -> Result<ArgType> {
     Ok(ArgType {
         name: arg.name.clone(),
-        typ: check_type(env, &arg.typ)?,
+        typ: check_type(env, &arg.typ, None)?, // args don't have comments
     })
 }
 
@@ -110,10 +110,11 @@ fn check_fields(env: &Env, fs: &[TypeField]) -> Result<Vec<Field>> {
     // field label duplication is checked in the parser
     let mut res = Vec::new();
     for f in fs.iter() {
-        let ty = check_type(env, &f.typ)?;
+        let ty = check_type(env, &f.typ, None)?;
         let field = Field {
             id: f.label.clone().into(),
             ty,
+            comment: f.comment().map(|lines| std::rc::Rc::new(lines.to_vec())),
         };
         res.push(field);
     }
@@ -124,7 +125,7 @@ fn check_meths(env: &Env, ms: &[Binding]) -> Result<Vec<(String, Type)>> {
     // binding duplication is checked in the parser
     let mut res = Vec::new();
     for meth in ms.iter() {
-        let t = check_type(env, &meth.typ)?;
+        let t = check_type(env, &meth.typ, meth.comment.as_ref().map(|c| c.lines()))?;
         if !env.pre && env.te.as_func(&t).is_err() {
             return Err(Error::msg(format!(
                 "method {} is a non-function type",
@@ -139,8 +140,8 @@ fn check_meths(env: &Env, ms: &[Binding]) -> Result<Vec<(String, Type)>> {
 fn check_defs(env: &mut Env, decs: &[Dec]) -> Result<()> {
     for dec in decs.iter() {
         match dec {
-            Dec::TypD(Binding { id, typ }) => {
-                let t = check_type(env, typ)?;
+            Dec::TypD(Binding { id, typ, comment }) => {
+                let t = check_type(env, typ, comment.as_ref().map(|c| c.lines()))?;
                 env.te.0.insert(id.to_string(), t);
             }
             Dec::ImportType(_) | Dec::ImportServ(_) => (),
@@ -174,7 +175,7 @@ fn check_cycle(env: &TypeEnv) -> Result<()> {
 
 fn check_decs(env: &mut Env, decs: &[Dec]) -> Result<()> {
     for dec in decs.iter() {
-        if let Dec::TypD(Binding { id, typ: _ }) = dec {
+        if let Dec::TypD(Binding { id, .. }) = dec {
             let duplicate = env.te.0.insert(id.to_string(), TypeInner::Unknown.into());
             if duplicate.is_some() {
                 return Err(Error::msg(format!("duplicate binding for {id}")));
@@ -189,23 +190,27 @@ fn check_decs(env: &mut Env, decs: &[Dec]) -> Result<()> {
     Ok(())
 }
 
-fn check_actor(env: &Env, actor: &Option<IDLType>) -> Result<Option<Type>> {
-    match actor {
-        None => Ok(None),
-        Some(IDLType::ClassT(ts, t)) => {
-            let mut args = Vec::new();
-            for arg in ts.iter() {
-                args.push(check_arg(env, arg)?);
+fn check_actor(env: &Env, actor: &Option<ActorBinding>) -> Result<Option<Type>> {
+    if let Some(ActorBinding { typ, comment }) = actor {
+        let comment = comment.as_ref().map(|c| c.lines());
+        match typ {
+            IDLType::ClassT(ts, t) => {
+                let mut args = Vec::new();
+                for arg in ts.iter() {
+                    args.push(check_arg(env, arg)?);
+                }
+                let serv = check_type(env, t, None)?;
+                env.te.as_service(&serv)?;
+                Ok(Some((TypeInner::Class(args, serv), comment).into()))
+            }
+            _ => {
+                let t = check_type(env, typ, comment)?;
+                env.te.as_service(&t)?;
+                Ok(Some(t))
             }
-            let serv = check_type(env, t)?;
-            env.te.as_service(&serv)?;
-            Ok(Some(TypeInner::Class(args, serv).into()))
-        }
-        Some(typ) => {
-            let t = check_type(env, typ)?;
-            env.te.as_service(&t)?;
-            Ok(Some(t))
         }
+    } else {
+        Ok(None)
     }
 }
 
@@ -301,7 +306,7 @@ fn merge_actor(
                         check_unique(ms.iter().map(|m| &m.0)).map_err(|e| {
                             Error::msg(format!("Duplicate imported method name: {e}"))
                         })?;
-                        let res: Type = TypeInner::Service(ms).into();
+                        let res: Type = (TypeInner::Service(ms), t.comment()).into();
                         Ok(Some(res))
                     }
                 },
diff --git a/rust/candid_parser/tests/assets/actor.did b/rust/candid_parser/tests/assets/actor.did
index 12a7e20d4..8d392d726 100644
--- a/rust/candid_parser/tests/assets/actor.did
+++ b/rust/candid_parser/tests/assets/actor.did
@@ -2,6 +2,7 @@ type f = func (int8) -> (int8);
 type g = f;
 type h = func (f) -> (f);
 type o = opt o;
+// This is a service comment
 service :
 {
   f : (nat) -> (h);
diff --git a/rust/candid_parser/tests/assets/class.did b/rust/candid_parser/tests/assets/class.did
index fb1fdfb7f..8b0899b57 100644
--- a/rust/candid_parser/tests/assets/class.did
+++ b/rust/candid_parser/tests/assets/class.did
@@ -1,6 +1,8 @@
 type Profile = record { age: nat8; name: text };
 type List = opt record { int; List };
+// This is a service comment
 service : (int, l : List, Profile) -> {
+  // This is a method comment
   get : () -> (List);
   set : (List) -> (List);
 }
diff --git a/rust/candid_parser/tests/assets/comment.did b/rust/candid_parser/tests/assets/comment.did
index e412fe385..a970500f3 100644
--- a/rust/candid_parser/tests/assets/comment.did
+++ b/rust/candid_parser/tests/assets/comment.did
@@ -1,4 +1,11 @@
-// line comment
+// ignored comment above import
+import "import/a.did";
+// ignored line comment
+
+// another ignored line comment
+// that spans multiple lines
+  // even indented
+
 /* gjkf
 jgfkg
 */
diff --git a/rust/candid_parser/tests/assets/example.did b/rust/candid_parser/tests/assets/example.did
index a5a47fee6..028c03ddc 100644
--- a/rust/candid_parser/tests/assets/example.did
+++ b/rust/candid_parser/tests/assets/example.did
@@ -1,22 +1,50 @@
+// This is an ignored import service comment
 import service "recursion.did";
+// This is an ignored import comment
 import "import/a.did";
+// This is another ignored import service comment
 import service "import/b/b.did";
+// This is a type comment
 type my_type = principal;
-type List = opt record { head: int; tail: List };
-type f = func (List, func (int32) -> (int64)) -> (opt List, res);
+
+// This is an ignored comment
+
+type List = opt record {
+  head: int;
+  // This is a field comment
+  tail: List;
+}; // This comment is ignored
+type f = func (List, func (int32) -> (int64)) -> (opt List, res); // This comment is ignored
+// This is another type comment
 type broker = service {
   find : (name: text) ->
-    (service {up:() -> (); current:() -> (nat32)});
+    (service {up:() -> (); current:() -> (nat32)}); // This comment is ignored
 };
 type nested = record { nat; nat; record {nat;int;}; record { nat; 0x2a:nat; nat8; }; 42:nat; 40:nat; variant{ A; 0x2a; B; C }; };
-type res = variant { Ok: record{int;nat}; Err: record{ error: text } };
-type nested_res = variant { Ok: variant { Ok; Err }; Err: variant { Ok: record { content: text }; Err: record {int} } };
+type res = variant { Ok: record{int;nat}; Err: record{ error: text } }; // This comment is ignored
+type nested_res = variant { // This comment is ignored
+  // This is a variant comment
+  Ok : variant { Ok; Err };      // This comment is ignored
+  // This is another variant comment
+  // that spans multiple lines for variants
+  Err : variant { Ok: record { content: text }; Err: record {int} }; // This comment is ignored
+};
 
+// This is another ignored comment
+
+// This is a service comment
+// that spans multiple lines for services
 service server : {
   f1 : (list, test: blob, opt bool) -> () oneway;
-  g1 : (my_type, List, opt List, nested) -> (int, broker, nested_res) query;
-  h : (vec opt text, variant { A: nat; B: opt text }, opt List) -> (record { id: nat; 0x2a: record {} });
-  i : f;
+  // This comment is ignored
+  // even indented
+
+  // This is a method comment
+  g1 : (my_type, List, opt List, nested) -> (int, broker, nested_res) query; // This comment is ignored
+  h : (vec opt text, variant { A: nat; B: opt text }, opt List) -> (record { id: nat; 0x2a: record {} }); // This comment is ignored
+  i : f;// This comment is ignored
+  // This is another method comment
+  // that spans multiple lines for methods
   x : (a,b) -> (opt a, opt b, variant { Ok: record { result: text }; Err: variant {a;b} }) composite_query;
 }
 
diff --git a/rust/candid_parser/tests/assets/import/a.did b/rust/candid_parser/tests/assets/import/a.did
index ebdcddc77..499b42f2f 100644
--- a/rust/candid_parser/tests/assets/import/a.did
+++ b/rust/candid_parser/tests/assets/import/a.did
@@ -1,5 +1,6 @@
 import "b/b.did";
 type a = variant {a;b:b};
 service : (a,b) -> {
+  // This comment is ignored because this method
   f : (b) -> (a);
 }
diff --git a/rust/candid_parser/tests/assets/import/b/b.did b/rust/candid_parser/tests/assets/import/b/b.did
index b28cb7773..3b2de9716 100644
--- a/rust/candid_parser/tests/assets/import/b/b.did
+++ b/rust/candid_parser/tests/assets/import/b/b.did
@@ -1,4 +1,7 @@
+// This is a type comment
 type b = record { int;nat };
+// This service comment is always ignored because it's in an imported file
 service : {
+  // This is a method comment on an imported service
   bbbbb : (b) -> ();
 }
diff --git a/rust/candid_parser/tests/assets/management.did b/rust/candid_parser/tests/assets/management.did
index 04f425222..756226db2 100644
--- a/rust/candid_parser/tests/assets/management.did
+++ b/rust/candid_parser/tests/assets/management.did
@@ -1,3 +1,5 @@
+// This is a comment
+// with multiple lines
 type canister_id = principal;
 type user_id = principal;
 type wasm_module = blob;
@@ -9,13 +11,17 @@ type canister_settings = record {
   freezing_threshold : opt nat;
 };
 
+// This is a second comment
 type definite_canister_settings = record {
   controllers : vec principal;
   compute_allocation : nat;
+  // This is a field comment
   memory_allocation : nat;
   freezing_threshold : nat;
 };
 
+// This is an ignored comment
+
 type http_header = record { name: text; value: text };
 
 type http_response = record {
@@ -29,7 +35,10 @@ type ecdsa_curve = variant { secp256k1; };
 type satoshi = nat64;
 
 type bitcoin_network = variant {
+  // This is a variant comment
   mainnet;
+  // This is another variant comment
+  // that spans multiple lines for variants
   testnet;
 };
 
@@ -81,6 +90,7 @@ type send_transaction_request = record {
 
 type millisatoshi_per_byte = nat64;
 
+// This is a service comment
 service ic : {
   create_canister : (record {
     settings : opt canister_settings
diff --git a/rust/candid_parser/tests/assets/ok/actor.d.ts b/rust/candid_parser/tests/assets/ok/actor.d.ts
index 7e88ad9b3..38873aef7 100644
--- a/rust/candid_parser/tests/assets/ok/actor.d.ts
+++ b/rust/candid_parser/tests/assets/ok/actor.d.ts
@@ -6,6 +6,9 @@ export type f = ActorMethod<[number], number>;
 export type g = f;
 export type h = ActorMethod<[[Principal, string]], [Principal, string]>;
 export type o = [] | [o];
+/**
+ * This is a service comment
+ */
 export interface _SERVICE {
   'f' : ActorMethod<[bigint], [Principal, string]>,
   'g' : f,
diff --git a/rust/candid_parser/tests/assets/ok/actor.did b/rust/candid_parser/tests/assets/ok/actor.did
index b9616ec5b..2be70b17c 100644
--- a/rust/candid_parser/tests/assets/ok/actor.did
+++ b/rust/candid_parser/tests/assets/ok/actor.did
@@ -2,4 +2,5 @@ type f = func (int8) -> (int8);
 type g = f;
 type h = func (f) -> (f);
 type o = opt o;
+// This is a service comment
 service : { f : (nat) -> (h); g : f; h : g; o : (o) -> (o) }
diff --git a/rust/candid_parser/tests/assets/ok/actor.mo b/rust/candid_parser/tests/assets/ok/actor.mo
index 9de5b8b1a..cb7318c5f 100644
--- a/rust/candid_parser/tests/assets/ok/actor.mo
+++ b/rust/candid_parser/tests/assets/ok/actor.mo
@@ -6,6 +6,7 @@ module {
   public type g = f;
   public type h = shared f -> async f;
   public type o = ?o;
+  /// This is a service comment
   public type Self = actor {
     f : shared Nat -> async h;
     g : f;
diff --git a/rust/candid_parser/tests/assets/ok/actor.rs b/rust/candid_parser/tests/assets/ok/actor.rs
index 2b30a3050..3434fc54a 100644
--- a/rust/candid_parser/tests/assets/ok/actor.rs
+++ b/rust/candid_parser/tests/assets/ok/actor.rs
@@ -10,6 +10,7 @@ pub type G = F;
 #[derive(CandidType, Deserialize)]
 pub struct O(pub Option<Box<O>>);
 
+/// This is a service comment
 pub struct Service(pub Principal);
 impl Service {
   pub async fn f(&self, arg0: &candid::Nat) -> Result<(H,)> {
@@ -25,6 +26,8 @@ impl Service {
     ic_cdk::call(self.0, "o", (arg0,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
+/// This is a service comment
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/class.d.ts b/rust/candid_parser/tests/assets/ok/class.d.ts
index 412ee8514..76337a64d 100644
--- a/rust/candid_parser/tests/assets/ok/class.d.ts
+++ b/rust/candid_parser/tests/assets/ok/class.d.ts
@@ -4,7 +4,13 @@ import type { IDL } from '@dfinity/candid';
 
 export type List = [] | [[bigint, List]];
 export interface Profile { 'age' : number, 'name' : string }
+/**
+ * This is a service comment
+ */
 export interface _SERVICE {
+  /**
+   * This is a method comment
+   */
   'get' : ActorMethod<[], List>,
   'set' : ActorMethod<[List], List>,
 }
diff --git a/rust/candid_parser/tests/assets/ok/class.did b/rust/candid_parser/tests/assets/ok/class.did
index 4850a508e..8bbf7bb84 100644
--- a/rust/candid_parser/tests/assets/ok/class.did
+++ b/rust/candid_parser/tests/assets/ok/class.did
@@ -1,6 +1,8 @@
 type List = opt record { int; List };
 type Profile = record { age : nat8; name : text };
+// This is a service comment
 service : (int, l : List, Profile) -> {
+  // This is a method comment
   get : () -> (List);
   set : (List) -> (List);
 }
diff --git a/rust/candid_parser/tests/assets/ok/class.mo b/rust/candid_parser/tests/assets/ok/class.mo
index 41ab07b63..88d3c9e95 100644
--- a/rust/candid_parser/tests/assets/ok/class.mo
+++ b/rust/candid_parser/tests/assets/ok/class.mo
@@ -4,7 +4,9 @@
 module {
   public type List = ?(Int, List);
   public type Profile = { age : Nat8; name : Text };
+  /// This is a service comment
   public type Self = (Int, l : List, Profile) -> async actor {
+    /// This is a method comment
     get : shared () -> async List;
     set : shared List -> async List;
   }
diff --git a/rust/candid_parser/tests/assets/ok/class.rs b/rust/candid_parser/tests/assets/ok/class.rs
index be0429b4a..f92f57070 100644
--- a/rust/candid_parser/tests/assets/ok/class.rs
+++ b/rust/candid_parser/tests/assets/ok/class.rs
@@ -12,6 +12,7 @@ pub struct Profile { pub age: u8, pub name: String }
 fn init(arg0: candid::Int, l: List, arg2: Profile) {
   unimplemented!()
 }
+/// This is a method comment
 #[ic_cdk::update]
 fn get() -> List {
   unimplemented!()
@@ -21,6 +22,10 @@ fn set(arg0: List) -> List {
   unimplemented!()
 }
 #[link_section = "icp:public candid:service"]
-pub static __SERVICE: [u8; 94] = *br#"type List = opt record { int; List };
-service : { get : () -> (List); set : (List) -> (List) }"#;
+pub static __SERVICE: [u8; 129] = *br#"type List = opt record { int; List };
+service : {
+  // This is a method comment
+  get : () -> (List);
+  set : (List) -> (List);
+}"#;
 
diff --git a/rust/candid_parser/tests/assets/ok/comment.d.ts b/rust/candid_parser/tests/assets/ok/comment.d.ts
index 48942cde1..e7f9de080 100644
--- a/rust/candid_parser/tests/assets/ok/comment.d.ts
+++ b/rust/candid_parser/tests/assets/ok/comment.d.ts
@@ -2,5 +2,11 @@ import type { Principal } from '@dfinity/principal';
 import type { ActorMethod } from '@dfinity/agent';
 import type { IDL } from '@dfinity/candid';
 
+export type a = { 'a' : null } |
+  { 'b' : b };
+/**
+ * This is a type comment
+ */
+export type b = [bigint, bigint];
 export type id = number;
 
diff --git a/rust/candid_parser/tests/assets/ok/comment.did b/rust/candid_parser/tests/assets/ok/comment.did
index 04bf164ff..5b849fc6e 100644
--- a/rust/candid_parser/tests/assets/ok/comment.did
+++ b/rust/candid_parser/tests/assets/ok/comment.did
@@ -1,2 +1,5 @@
+type a = variant { a; b : b };
+// This is a type comment
+type b = record { int; nat };
 type id = nat8;
 
diff --git a/rust/candid_parser/tests/assets/ok/comment.js b/rust/candid_parser/tests/assets/ok/comment.js
index 1f63d4782..45fe1ff2d 100644
--- a/rust/candid_parser/tests/assets/ok/comment.js
+++ b/rust/candid_parser/tests/assets/ok/comment.js
@@ -1,2 +1,5 @@
+const b = IDL.Rec();
+const a = IDL.Variant({ 'a' : IDL.Null, 'b' : b });
+b.fill(IDL.Tuple(IDL.Int, IDL.Nat));
 const id = IDL.Nat8;
 
diff --git a/rust/candid_parser/tests/assets/ok/comment.mo b/rust/candid_parser/tests/assets/ok/comment.mo
index baf858e78..4ea8ce67f 100644
--- a/rust/candid_parser/tests/assets/ok/comment.mo
+++ b/rust/candid_parser/tests/assets/ok/comment.mo
@@ -2,6 +2,9 @@
 // Please use `import service "ic:canister_id"` instead to call canisters on the IC if possible.
 
 module {
+  public type a = { #a; #b : b };
+  /// This is a type comment
+  public type b = (Int, Nat);
   public type id = Nat8;
 
 }
diff --git a/rust/candid_parser/tests/assets/ok/comment.rs b/rust/candid_parser/tests/assets/ok/comment.rs
index 958f42fac..10af3ebb1 100644
--- a/rust/candid_parser/tests/assets/ok/comment.rs
+++ b/rust/candid_parser/tests/assets/ok/comment.rs
@@ -4,6 +4,11 @@
 use candid::{self, CandidType, Deserialize, Principal};
 use ic_cdk::api::call::CallResult as Result;
 
+#[derive(CandidType, Deserialize)]
+pub enum A { #[serde(rename="a")] A, #[serde(rename="b")] B(Box<B>) }
+/// This is a type comment
+#[derive(CandidType, Deserialize)]
+pub struct B (pub candid::Int,pub candid::Nat,);
 pub type Id = u8;
 
 
diff --git a/rust/candid_parser/tests/assets/ok/cyclic.rs b/rust/candid_parser/tests/assets/ok/cyclic.rs
index 33eaa02fe..cb12343cc 100644
--- a/rust/candid_parser/tests/assets/ok/cyclic.rs
+++ b/rust/candid_parser/tests/assets/ok/cyclic.rs
@@ -18,6 +18,7 @@ impl Service {
     ic_cdk::call(self.0, "f", (arg0,arg1,arg2,arg3,arg4,arg5,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/empty.rs b/rust/candid_parser/tests/assets/ok/empty.rs
index 4477e9f99..899477cc8 100644
--- a/rust/candid_parser/tests/assets/ok/empty.rs
+++ b/rust/candid_parser/tests/assets/ok/empty.rs
@@ -27,6 +27,7 @@ impl Service {
     ic_cdk::call(self.0, "h", (arg0,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/escape.rs b/rust/candid_parser/tests/assets/ok/escape.rs
index 0fde3e5d9..96feb0727 100644
--- a/rust/candid_parser/tests/assets/ok/escape.rs
+++ b/rust/candid_parser/tests/assets/ok/escape.rs
@@ -22,6 +22,7 @@ impl Service {
     ic_cdk::call(self.0, "\n\'\"\'\'\"\"\r\t", (arg0,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/example.d.ts b/rust/candid_parser/tests/assets/ok/example.d.ts
index a3975f37b..284d1e0ed 100644
--- a/rust/candid_parser/tests/assets/ok/example.d.ts
+++ b/rust/candid_parser/tests/assets/ok/example.d.ts
@@ -4,13 +4,30 @@ import type { IDL } from '@dfinity/candid';
 
 export type A = B;
 export type B = [] | [A];
-export type List = [] | [{ 'head' : bigint, 'tail' : List }];
+export type List = [] | [
+  {
+    'head' : bigint,
+    /**
+     * This is a field comment
+     */
+    'tail' : List,
+  }
+];
 export type a = { 'a' : null } |
   { 'b' : b };
+/**
+ * This is a type comment
+ */
 export type b = [bigint, bigint];
+/**
+ * This is another type comment
+ */
 export interface broker { 'find' : ActorMethod<[string], Principal> }
 export type f = ActorMethod<[List, [Principal, string]], [[] | [List], res]>;
 export type list = [] | [node];
+/**
+ * This is a type comment
+ */
 export type my_type = Principal;
 export interface nested {
   _0_ : bigint,
@@ -24,8 +41,21 @@ export interface nested {
     { 'C' : null },
   _42_ : bigint,
 }
-export type nested_res = { 'Ok' : { 'Ok' : null } | { 'Err' : null } } |
-  { 'Err' : { 'Ok' : { 'content' : string } } | { 'Err' : [bigint] } };
+export type nested_res = {
+    /**
+     * This is a variant comment
+     */
+    'Ok' : { 'Ok' : null } |
+      { 'Err' : null }
+  } |
+  {
+    /**
+     * This is another variant comment
+     * that spans multiple lines for variants
+     */
+    'Err' : { 'Ok' : { 'content' : string } } |
+      { 'Err' : [bigint] }
+  };
 export interface node { 'head' : bigint, 'tail' : list }
 export type res = { 'Ok' : [bigint, bigint] } |
   { 'Err' : { 'error' : string } };
@@ -36,11 +66,21 @@ export type tree = {
     'branch' : { 'val' : bigint, 'left' : tree, 'right' : tree }
   } |
   { 'leaf' : bigint };
+/**
+ * This is a service comment
+ * that spans multiple lines for services
+ */
 export interface _SERVICE {
+  /**
+   * This is a method comment on an imported service
+   */
   'bbbbb' : ActorMethod<[b], undefined>,
   'f' : t,
   'f1' : ActorMethod<[list, Uint8Array | number[], [] | [boolean]], undefined>,
   'g' : ActorMethod<[list], [B, tree, stream]>,
+  /**
+   * This is a method comment
+   */
   'g1' : ActorMethod<
     [my_type, List, [] | [List], nested],
     [bigint, Principal, nested_res]
@@ -55,6 +95,10 @@ export interface _SERVICE {
     { _42_ : {}, 'id' : bigint }
   >,
   'i' : f,
+  /**
+   * This is another method comment
+   * that spans multiple lines for methods
+   */
   'x' : ActorMethod<
     [a, b],
     [
diff --git a/rust/candid_parser/tests/assets/ok/example.did b/rust/candid_parser/tests/assets/ok/example.did
index 6bd434f09..7e45a77a9 100644
--- a/rust/candid_parser/tests/assets/ok/example.did
+++ b/rust/candid_parser/tests/assets/ok/example.did
@@ -1,13 +1,20 @@
 type A = B;
 type B = opt A;
-type List = opt record { head : int; tail : List };
+type List = opt record {
+  head : int;
+  // This is a field comment
+  tail : List;
+};
 type a = variant { a; b : b };
+// This is a type comment
 type b = record { int; nat };
+// This is another type comment
 type broker = service {
   find : (name : text) -> (service { current : () -> (nat32); up : () -> () });
 };
 type f = func (List, func (int32) -> (int64)) -> (opt List, res);
 type list = opt node;
+// This is a type comment
 type my_type = principal;
 type nested = record {
   0 : nat;
@@ -19,7 +26,10 @@ type nested = record {
   42 : nat;
 };
 type nested_res = variant {
+  // This is a variant comment
   Ok : variant { Ok; Err };
+  // This is another variant comment
+  // that spans multiple lines for variants
   Err : variant { Ok : record { content : text }; Err : record { int } };
 };
 type node = record { head : nat; tail : list };
@@ -31,16 +41,22 @@ type tree = variant {
   branch : record { val : int; left : tree; right : tree };
   leaf : int;
 };
+// This is a service comment
+// that spans multiple lines for services
 service : {
+  // This is a method comment on an imported service
   bbbbb : (b) -> ();
   f : t;
   f1 : (list, test : blob, opt bool) -> () oneway;
   g : (list) -> (B, tree, stream);
+  // This is a method comment
   g1 : (my_type, List, opt List, nested) -> (int, broker, nested_res) query;
   h : (vec opt text, variant { A : nat; B : opt text }, opt List) -> (
       record { 42 : record {}; id : nat },
     );
   i : f;
+  // This is another method comment
+  // that spans multiple lines for methods
   x : (a, b) -> (
       opt a,
       opt b,
diff --git a/rust/candid_parser/tests/assets/ok/example.mo b/rust/candid_parser/tests/assets/ok/example.mo
index 76bb1f058..7f22878b9 100644
--- a/rust/candid_parser/tests/assets/ok/example.mo
+++ b/rust/candid_parser/tests/assets/ok/example.mo
@@ -4,9 +4,15 @@
 module {
   public type A = B;
   public type B = ?A;
-  public type List = ?{ head : Int; tail : List };
+  public type List = ?{
+    head : Int;
+    /// This is a field comment
+    tail : List;
+  };
   public type a = { #a; #b : b };
+  /// This is a type comment
   public type b = (Int, Nat);
+  /// This is another type comment
   public type broker = actor {
     find : shared (name : Text) -> async actor {
         current : shared () -> async Nat32;
@@ -18,6 +24,7 @@ module {
       res,
     );
   public type list = ?node;
+  /// This is a type comment
   public type my_type = Principal;
   public type nested = {
     _0_  : Nat;
@@ -29,7 +36,10 @@ module {
     _42_  : Nat;
   };
   public type nested_res = {
+    /// This is a variant comment
     #Ok : { #Ok; #Err };
+    /// This is another variant comment
+    /// that spans multiple lines for variants
     #Err : { #Ok : { content : Text }; #Err : { _0_  : Int } };
   };
   public type node = { head : Nat; tail : list };
@@ -41,11 +51,15 @@ module {
     #branch : { val : Int; left : tree; right : tree };
     #leaf : Int;
   };
+  /// This is a service comment
+  /// that spans multiple lines for services
   public type Self = actor {
+    /// This is a method comment on an imported service
     bbbbb : shared b -> async ();
     f : t;
     f1 : shared (list, test : Blob, ?Bool) -> ();
     g : shared list -> async (B, tree, stream);
+    /// This is a method comment
     g1 : shared query (my_type, List, ?List, nested) -> async (
         Int,
         broker,
@@ -56,6 +70,8 @@ module {
         id : Nat;
       };
     i : f;
+    /// This is another method comment
+    /// that spans multiple lines for methods
     x : shared composite query (a, b) -> async (
         ?a,
         ?b,
diff --git a/rust/candid_parser/tests/assets/ok/example.rs b/rust/candid_parser/tests/assets/ok/example.rs
index c4a9d4002..58a29ceb2 100644
--- a/rust/candid_parser/tests/assets/ok/example.rs
+++ b/rust/candid_parser/tests/assets/ok/example.rs
@@ -4,6 +4,7 @@
 use candid::{self, CandidType, Deserialize, Principal};
 use ic_cdk::api::call::CallResult as Result;
 
+/// This is a type comment
 #[derive(CandidType, Deserialize, Debug)]
 pub(crate) struct B (pub(crate) candid::Int,pub(crate) u128,);
 #[derive(CandidType, Deserialize, Debug)]
@@ -33,12 +34,14 @@ candid::define_service!(pub(crate) S : {
   "g" : candid::func!((List) -> (B, Tree, Stream));
 });
 candid::define_function!(pub(crate) T : (S) -> ());
+/// This is a type comment
 type CanisterId = Principal;
 #derive[CandidType, Deserialize, Clone]
 pub(crate) struct ListInner {
   #[serde(skip_deserializing)]
   #[serde(rename="head")]
   HEAD: candid::Int,
+  /// This is a field comment
   #[serde(skip_deserializing)]
   tail: Arc<MyList>,
 }
@@ -73,6 +76,7 @@ candid::define_service!(pub BrokerReturn : {
   "current" : candid::func!(() -> (u32));
   "up" : candid::func!(() -> ());
 });
+/// This is another type comment
 candid::define_service!(pub(crate) Broker : {
   "find" : candid::func!((String) -> (BrokerReturn));
 });
@@ -102,8 +106,11 @@ pub(crate) struct XRet2Ok { pub(crate) result: String }
 #[derive(CandidType, Deserialize, Debug)]
 pub(crate) enum Error { #[serde(rename="a")] A, #[serde(rename="b")] B }
 
+/// This is a service comment
+/// that spans multiple lines for services
 pub struct Service(pub Principal);
 impl Service {
+  /// This is a method comment on an imported service
   pub async fn bbbbb(&self, arg0: &B) -> Result<()> {
     ic_cdk::call(self.0, "bbbbb", (arg0,)).await
   }
@@ -116,6 +123,7 @@ impl Service {
   pub async fn g(&self, arg0: &List) -> Result<(B,Tree,Stream,)> {
     ic_cdk::call(self.0, "g", (arg0,)).await
   }
+  /// This is a method comment
   pub async fn G11(&self, id: &CanisterId, list: &MyList, is_okay: &Option<MyList>, arg3: &Nested) -> Result<(i128,Broker,NestedRes,)> {
     ic_cdk::call(self.0, "g1", (id,list,is_okay,arg3,)).await
   }
@@ -125,17 +133,26 @@ impl Service {
   pub async fn i(&self, arg0: &MyList, arg1: &FArg1) -> Result<(Option<MyList>,Res,)> {
     ic_cdk::call(self.0, "i", (arg0,arg1,)).await
   }
+  /// This is another method comment
+  /// that spans multiple lines for methods
   pub async fn x(&self, arg0: &A, arg1: &B) -> Result<(Option<A>,Option<B>,std::result::Result<XRet2Ok, Error>,)> {
     ic_cdk::call(self.0, "x", (arg0,arg1,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
+/// This is a service comment
+/// that spans multiple lines for services
 pub const service : Service = Service(CANISTER_ID);
 #[test]
 fn test_Arc_MyList_() {
   // Generated from ListInner.record.tail.use_type = "Arc<MyList>"
   let candid_src = r#"type List = opt ListInner;
-type ListInner = record { head : int; tail : List };
+type ListInner = record {
+  head : int;
+  // This is a field comment
+  tail : List;
+};
 (List)"#;
   candid_parser::utils::check_rust_type::<Arc<MyList>>(candid_src).unwrap();
 }
diff --git a/rust/candid_parser/tests/assets/ok/fieldnat.rs b/rust/candid_parser/tests/assets/ok/fieldnat.rs
index 3d335e76b..43c063fd1 100644
--- a/rust/candid_parser/tests/assets/ok/fieldnat.rs
+++ b/rust/candid_parser/tests/assets/ok/fieldnat.rs
@@ -51,6 +51,7 @@ impl Service {
     ic_cdk::call(self.0, "foo", (arg0,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/keyword.rs b/rust/candid_parser/tests/assets/ok/keyword.rs
index e0b8ddb7b..d25756994 100644
--- a/rust/candid_parser/tests/assets/ok/keyword.rs
+++ b/rust/candid_parser/tests/assets/ok/keyword.rs
@@ -76,6 +76,7 @@ impl Service {
     ic_cdk::call(self.0, "variant", (arg0,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/management.d.ts b/rust/candid_parser/tests/assets/ok/management.d.ts
index ca60e354d..e986e8ecc 100644
--- a/rust/candid_parser/tests/assets/ok/management.d.ts
+++ b/rust/candid_parser/tests/assets/ok/management.d.ts
@@ -3,9 +3,24 @@ import type { ActorMethod } from '@dfinity/agent';
 import type { IDL } from '@dfinity/candid';
 
 export type bitcoin_address = string;
-export type bitcoin_network = { 'mainnet' : null } |
-  { 'testnet' : null };
+export type bitcoin_network = {
+    /**
+     * This is a variant comment
+     */
+    'mainnet' : null
+  } |
+  {
+    /**
+     * This is another variant comment
+     * that spans multiple lines for variants
+     */
+    'testnet' : null
+  };
 export type block_hash = Uint8Array | number[];
+/**
+ * This is a comment
+ * with multiple lines
+ */
 export type canister_id = Principal;
 export interface canister_settings {
   'freezing_threshold' : [] | [bigint],
@@ -13,9 +28,15 @@ export interface canister_settings {
   'memory_allocation' : [] | [bigint],
   'compute_allocation' : [] | [bigint],
 }
+/**
+ * This is a second comment
+ */
 export interface definite_canister_settings {
   'freezing_threshold' : bigint,
   'controllers' : Array<Principal>,
+  /**
+   * This is a field comment
+   */
   'memory_allocation' : bigint,
   'compute_allocation' : bigint,
 }
@@ -62,7 +83,13 @@ export interface utxo {
   'outpoint' : outpoint,
 }
 export type wasm_module = Uint8Array | number[];
+/**
+ * This is a service comment
+ */
 export interface _SERVICE {
+  /**
+   * bitcoin interface
+   */
   'bitcoin_get_balance' : ActorMethod<[get_balance_request], satoshi>,
   'bitcoin_get_current_fee_percentiles' : ActorMethod<
     [get_current_fee_percentiles_request],
@@ -92,6 +119,9 @@ export interface _SERVICE {
   >,
   'delete_canister' : ActorMethod<[{ 'canister_id' : canister_id }], undefined>,
   'deposit_cycles' : ActorMethod<[{ 'canister_id' : canister_id }], undefined>,
+  /**
+   * Threshold ECDSA signature
+   */
   'ecdsa_public_key' : ActorMethod<
     [
       {
@@ -138,6 +168,9 @@ export interface _SERVICE {
     ],
     undefined
   >,
+  /**
+   * provisional interfaces for the pre-ledger world
+   */
   'provisional_create_canister_with_cycles' : ActorMethod<
     [
       {
diff --git a/rust/candid_parser/tests/assets/ok/management.did b/rust/candid_parser/tests/assets/ok/management.did
index 4af885072..f43aca1fb 100644
--- a/rust/candid_parser/tests/assets/ok/management.did
+++ b/rust/candid_parser/tests/assets/ok/management.did
@@ -1,6 +1,14 @@
 type bitcoin_address = text;
-type bitcoin_network = variant { mainnet; testnet };
+type bitcoin_network = variant {
+  // This is a variant comment
+  mainnet;
+  // This is another variant comment
+  // that spans multiple lines for variants
+  testnet;
+};
 type block_hash = blob;
+// This is a comment
+// with multiple lines
 type canister_id = principal;
 type canister_settings = record {
   freezing_threshold : opt nat;
@@ -8,9 +16,11 @@ type canister_settings = record {
   memory_allocation : opt nat;
   compute_allocation : opt nat;
 };
+// This is a second comment
 type definite_canister_settings = record {
   freezing_threshold : nat;
   controllers : vec principal;
+  // This is a field comment
   memory_allocation : nat;
   compute_allocation : nat;
 };
@@ -48,7 +58,9 @@ type send_transaction_request = record {
 type user_id = principal;
 type utxo = record { height : nat32; value : satoshi; outpoint : outpoint };
 type wasm_module = blob;
+// This is a service comment
 service : {
+  // bitcoin interface
   bitcoin_get_balance : (get_balance_request) -> (satoshi);
   bitcoin_get_current_fee_percentiles : (
       get_current_fee_percentiles_request,
@@ -70,6 +82,7 @@ service : {
     );
   delete_canister : (record { canister_id : canister_id }) -> ();
   deposit_cycles : (record { canister_id : canister_id }) -> ();
+  // Threshold ECDSA signature
   ecdsa_public_key : (
       record {
         key_id : record { name : text; curve : ecdsa_curve };
@@ -100,6 +113,7 @@ service : {
         canister_id : canister_id;
       },
     ) -> ();
+  // provisional interfaces for the pre-ledger world
   provisional_create_canister_with_cycles : (
       record {
         settings : opt canister_settings;
diff --git a/rust/candid_parser/tests/assets/ok/management.mo b/rust/candid_parser/tests/assets/ok/management.mo
index 0609c7387..d7c7dc793 100644
--- a/rust/candid_parser/tests/assets/ok/management.mo
+++ b/rust/candid_parser/tests/assets/ok/management.mo
@@ -3,8 +3,16 @@
 
 module {
   public type bitcoin_address = Text;
-  public type bitcoin_network = { #mainnet; #testnet };
+  public type bitcoin_network = {
+    /// This is a variant comment
+    #mainnet;
+    /// This is another variant comment
+    /// that spans multiple lines for variants
+    #testnet;
+  };
   public type block_hash = Blob;
+  /// This is a comment
+  /// with multiple lines
   public type canister_id = Principal;
   public type canister_settings = {
     freezing_threshold : ?Nat;
@@ -12,9 +20,11 @@ module {
     memory_allocation : ?Nat;
     compute_allocation : ?Nat;
   };
+  /// This is a second comment
   public type definite_canister_settings = {
     freezing_threshold : Nat;
     controllers : [Principal];
+    /// This is a field comment
     memory_allocation : Nat;
     compute_allocation : Nat;
   };
@@ -54,7 +64,9 @@ module {
   public type user_id = Principal;
   public type utxo = { height : Nat32; value : satoshi; outpoint : outpoint };
   public type wasm_module = Blob;
+  /// This is a service comment
   public type Self = actor {
+    /// bitcoin interface
     bitcoin_get_balance : shared get_balance_request -> async satoshi;
     bitcoin_get_current_fee_percentiles : shared get_current_fee_percentiles_request -> async [
         millisatoshi_per_byte
@@ -74,6 +86,7 @@ module {
       };
     delete_canister : shared { canister_id : canister_id } -> async ();
     deposit_cycles : shared { canister_id : canister_id } -> async ();
+    /// Threshold ECDSA signature
     ecdsa_public_key : shared {
         key_id : { name : Text; curve : ecdsa_curve };
         canister_id : ?canister_id;
@@ -99,6 +112,7 @@ module {
         mode : { #reinstall; #upgrade; #install };
         canister_id : canister_id;
       } -> async ();
+    /// provisional interfaces for the pre-ledger world
     provisional_create_canister_with_cycles : shared {
         settings : ?canister_settings;
         specified_id : ?canister_id;
diff --git a/rust/candid_parser/tests/assets/ok/management.rs b/rust/candid_parser/tests/assets/ok/management.rs
index 311f8e1d6..e38cc7f88 100644
--- a/rust/candid_parser/tests/assets/ok/management.rs
+++ b/rust/candid_parser/tests/assets/ok/management.rs
@@ -6,8 +6,11 @@ type Result<T> = std::result::Result<T, ic_agent::AgentError>;
 
 #[derive(CandidType, Deserialize)]
 pub enum BitcoinNetwork {
+  /// This is a variant comment
   #[serde(rename="mainnet")]
   Mainnet,
+  /// This is another variant comment
+  /// that spans multiple lines for variants
   #[serde(rename="testnet")]
   Testnet,
 }
@@ -52,6 +55,8 @@ pub struct SendTransactionRequest {
   pub transaction: serde_bytes::ByteBuf,
   pub network: BitcoinNetwork,
 }
+/// This is a comment
+/// with multiple lines
 pub type CanisterId = Principal;
 #[derive(CandidType, Deserialize)]
 pub struct CanisterStatusArg { pub canister_id: CanisterId }
@@ -64,10 +69,12 @@ pub enum CanisterStatusRetStatus {
   #[serde(rename="running")]
   Running,
 }
+/// This is a second comment
 #[derive(CandidType, Deserialize)]
 pub struct DefiniteCanisterSettings {
   pub freezing_threshold: candid::Nat,
   pub controllers: Vec<Principal>,
+  /// This is a field comment
   pub memory_allocation: candid::Nat,
   pub compute_allocation: candid::Nat,
 }
@@ -203,8 +210,10 @@ pub struct UpdateSettingsArg {
   pub settings: CanisterSettings,
 }
 
+/// This is a service comment
 pub struct Service<'a>(pub Principal, pub &'a ic_agent::Agent);
 impl<'a> Service<'a> {
+  /// bitcoin interface
   pub async fn bitcoin_get_balance(&self, arg0: &GetBalanceRequest) -> Result<Satoshi> {
     let args = Encode!(&arg0)?;
     let bytes = self.1.update(&self.0, "bitcoin_get_balance").with_arg(args).call_and_wait().await?;
@@ -245,6 +254,7 @@ impl<'a> Service<'a> {
     let bytes = self.1.update(&self.0, "deposit_cycles").with_arg(args).call_and_wait().await?;
     Ok(Decode!(&bytes)?)
   }
+  /// Threshold ECDSA signature
   pub async fn ecdsa_public_key(&self, arg0: &EcdsaPublicKeyArg) -> Result<EcdsaPublicKeyRet> {
     let args = Encode!(&arg0)?;
     let bytes = self.1.update(&self.0, "ecdsa_public_key").with_arg(args).call_and_wait().await?;
@@ -260,6 +270,7 @@ impl<'a> Service<'a> {
     let bytes = self.1.update(&self.0, "install_code").with_arg(args).call_and_wait().await?;
     Ok(Decode!(&bytes)?)
   }
+  /// provisional interfaces for the pre-ledger world
   pub async fn provisional_create_canister_with_cycles(&self, arg0: &ProvisionalCreateCanisterWithCyclesArg) -> Result<ProvisionalCreateCanisterWithCyclesRet> {
     let args = Encode!(&arg0)?;
     let bytes = self.1.update(&self.0, "provisional_create_canister_with_cycles").with_arg(args).call_and_wait().await?;
@@ -301,5 +312,6 @@ impl<'a> Service<'a> {
     Ok(Decode!(&bytes)?)
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 
diff --git a/rust/candid_parser/tests/assets/ok/recursion.rs b/rust/candid_parser/tests/assets/ok/recursion.rs
index 3eb52d95f..239310042 100644
--- a/rust/candid_parser/tests/assets/ok/recursion.rs
+++ b/rust/candid_parser/tests/assets/ok/recursion.rs
@@ -38,6 +38,7 @@ impl Service {
     ic_cdk::call(self.0, "g", (arg0,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/recursive_class.rs b/rust/candid_parser/tests/assets/ok/recursive_class.rs
index ce01cd0ea..6678e8ca0 100644
--- a/rust/candid_parser/tests/assets/ok/recursive_class.rs
+++ b/rust/candid_parser/tests/assets/ok/recursive_class.rs
@@ -12,6 +12,7 @@ impl Service {
     ic_cdk::call(self.0, "next", ()).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/service.rs b/rust/candid_parser/tests/assets/ok/service.rs
index 631c2095a..cbcf60cd7 100644
--- a/rust/candid_parser/tests/assets/ok/service.rs
+++ b/rust/candid_parser/tests/assets/ok/service.rs
@@ -30,6 +30,7 @@ impl Service {
     ic_cdk::call(self.0, "asVariant", ()).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/assets/ok/unicode.rs b/rust/candid_parser/tests/assets/ok/unicode.rs
index 87c596f46..b5bfbb954 100644
--- a/rust/candid_parser/tests/assets/ok/unicode.rs
+++ b/rust/candid_parser/tests/assets/ok/unicode.rs
@@ -42,6 +42,7 @@ impl Service {
     ic_cdk::call(self.0, "👀", (arg0,)).await
   }
 }
-pub const CANISTER_ID : Principal = Principal::from_slice(&[]); // aaaaa-aa
+/// Canister ID: `aaaaa-aa`
+pub const CANISTER_ID : Principal = Principal::from_slice(&[]);
 pub const service : Service = Service(CANISTER_ID);
 
diff --git a/rust/candid_parser/tests/parse_type.rs b/rust/candid_parser/tests/parse_type.rs
index ad9569404..547bd96a8 100644
--- a/rust/candid_parser/tests/parse_type.rs
+++ b/rust/candid_parser/tests/parse_type.rs
@@ -12,21 +12,30 @@ use std::path::Path;
 fn parse_idl_prog() {
     let prog = r#"
 import "test.did";
+// This is a comment
 type my_type = principal;
-type List = opt record { head: int; tail: List };
-type f = func (List, func (int32) -> (int64)) -> (opt List);
-type broker = service {
+type List = opt record {
+  head: int;
+  // This is a field comment
+  tail: List;
+}; // This comment is ignored
+type f = func (List, func (int32) -> (int64)) -> (opt List); // This comment is ignored
+type broker = service { // This comment is ignored
+  // This is a method comment
   find : (name: text) ->
-    (service {up:() -> (); current:() -> (nat32)});
+    (service {up:() -> (); current:() -> (nat32)});     // This comment is ignored
 };
 type nested = record { nat; nat; record { nat; 0x2a:nat; nat8; }; 42:nat; 40:nat; variant{ A; 0x2a; B; C }; };
 
+// Ignored comment
+
+// This is a service comment
 service server : {
   f : (test: blob, opt bool) -> () oneway;
-  g : (my_type, List, opt List) -> (int) query;
+  g : (my_type, List, opt List) -> (int) query; // This comment is ignored
   h : (vec opt text, variant { A: nat; B: opt text }, opt List) -> (record { id: nat; 0x2a: record {} });
   i : f;
-}
+};
     "#;
     prog.parse::<IDLProg>().unwrap();
 }