Merge pull request #128 from saona-raimundo/doc-comments

On wit sintax: formalizing documentation comments (second attempt)

Author: alexcrichton

WIT.md

@@ -58,6 +58,17 @@ comment ::= '//' character-that-isnt-a-newline*
           | '/*' any-unicode-character* '*/'
 ```
 
+There is a special type of comment called `documentation comment`. A 
+`doc-comment` is either a line comment preceded with `///` whichends at the next
+newline (`\n`) character or it's a block comment which starts with `/**` and ends 
+with `*/`. Note that block comments are allowed to be nested and their delimiters 
+must be balanced
+
+```wit
+doc-comment ::= '///' character-that-isnt-a-newline*
+          | '/**' any-unicode-character* '*/'
+```
+
 ### Operators
 
 There are some common operators in the lexical structure of `wit` used for

crates/parser/src/ast/resolve.rs

@@ -514,13 +514,13 @@ impl Resolver {
         }
         let mut docs = String::new();
         for doc in doc.docs.iter() {
-            if let Some(doc) = doc.strip_prefix("//") {
+            // Comments which are not doc-comments are silently ignored
+            if let Some(doc) = doc.strip_prefix("///") {
                 docs.push_str(doc.trim_start_matches('/').trim());
                 docs.push('\n');
-            } else {
-                assert!(doc.starts_with("/*"));
+            } else if let Some(doc) = doc.strip_prefix("/**") {
                 assert!(doc.ends_with("*/"));
-                for line in doc[2..doc.len() - 2].lines() {
+                for line in doc[..doc.len() - 2].lines() {
                     docs.push_str(line);
                     docs.push('\n');
                 }