Fix /// whitespace parsing, and fix tests to use /// comments.

crates/wit-parser/src/ast/resolve.rs

@@ -1282,7 +1282,9 @@ impl<'a> Resolver<'a> {
         for doc in doc.docs.iter() {
             // Comments which are not doc-comments are silently ignored
             if let Some(doc) = doc.strip_prefix("/// ") {
-                lines.push(doc);
+                lines.push(doc.trim_end());
+            } else if doc == "///\n" {
+                lines.push("");
             }
         }
         let contents = if lines.is_empty() {

crates/wit-parser/tests/ui/comments.wit

@@ -6,7 +6,7 @@ package foo:comments;
 // this is a comment
 /* this too */ /* is a comment */
 /* this /* is /* a */ nested */ comment */
-
+/// and this is a documentation comment
 interface foo {
   type x = u32;
 

crates/wit-parser/tests/ui/comments.wit.json

@@ -9,7 +9,7 @@
       },
       "functions": {},
       "docs": {
-        "contents": "hello\nworld\nwhy, yes\nthis is a comment\n* this too */\n* is a comment */\n* this /* is /* a */ nested */ comment */"
+        "contents": "and this is a documentation comment"
       },
       "package": 0
     }

crates/wit-parser/tests/ui/types.wit

@@ -54,7 +54,7 @@ interface types {
   type t52 = future<u32>;
   type t53 = future;
 
-  // type order doesn't matter
+  /// type order doesn't matter
   type foo = bar;
   type bar = u32;
 }

crates/wit-parser/tests/ui/wasi.wit

@@ -2,177 +2,178 @@ package wasi:filesystem;
 
 interface wasi {
   enum clockid {
-    // The clock measuring real time. Time value zero corresponds with
-    // 1970-01-01T00:00:00Z.
+    /// The clock measuring real time. Time value zero corresponds with
+    /// 1970-01-01T00:00:00Z.
     realtime,
-    // The store-wide monotonic clock, which is defined as a clock measuring
-    // real time, whose value cannot be adjusted and which cannot have negative
-    // clock jumps. The epoch of this clock is undefined. The absolute time
-    // value of this clock therefore has no meaning.
+    /// The store-wide monotonic clock, which is defined as a clock measuring
+    /// real time, whose value cannot be adjusted and which cannot have negative
+    /// clock jumps. The epoch of this clock is undefined. The absolute time
+    /// value of this clock therefore has no meaning.
     monotonic,
   }
 
-  // Timestamp in nanoseconds.
+  /// Timestamp in nanoseconds.
   type timestamp = u64;
 
-  // Error codes returned by functions.
-  // Not all of these error codes are returned by the functions provided by this
-  // API/ some are used in higher-level library layers, and others are provided
-  // merely for alignment with POSIX.
+  /// Error codes returned by functions.
+  ///
+  /// Not all of these error codes are returned by the functions provided by this
+  /// API/ some are used in higher-level library layers, and others are provided
+  /// merely for alignment with POSIX.
   enum errno {
-    // No error occurred. System call completed successfully.
+    /// No error occurred. System call completed successfully.
     success,
-    // Argument list too long.
+    /// Argument list too long.
     toobig,
-    // Permission denied.
+    /// Permission denied.
     access,
-    // Address in use.
+    /// Address in use.
     addrinuse,
-    // Address not available.
+    /// Address not available.
     addrnotavail,
-    // Address family not supported.
+    /// Address family not supported.
     afnosupport,
-    // Resource unavailable, or operation would block.
+    /// Resource unavailable, or operation would block.
     again,
-    // Connection already in progress.
+    /// Connection already in progress.
     already,
-    // Bad file descriptor.
+    /// Bad file descriptor.
     badf,
-    // Bad message.
+    /// Bad message.
     badmsg,
-    // Device or resource busy.
+    /// Device or resource busy.
     busy,
-    // Operation canceled.
+    /// Operation canceled.
     canceled,
-    // No child processes.
+    /// No child processes.
     child,
-    // Connection aborted.
+    /// Connection aborted.
     connaborted,
-    // Connection refused.
+    /// Connection refused.
     connrefused,
-    // Connection reset.
+    /// Connection reset.
     connreset,
-    // Resource deadlock would occur.
+    /// Resource deadlock would occur.
     deadlk,
-    // Destination address required.
+    /// Destination address required.
     destaddrreq,
-    // Mathematics argument out of domain of function.
+    /// Mathematics argument out of domain of function.
     dom,
-    // Reserved.
+    /// Reserved.
     dquot,
-    // File exists.
+    /// File exists.
     exist,
-    // Bad address.
+    /// Bad address.
     fault,
-    // File too large.
+    /// File too large.
     fbig,
-    // Host is unreachable.
+    /// Host is unreachable.
     hostunreach,
-    // Identifier removed.
+    /// Identifier removed.
     idrm,
-    // Illegal byte sequence.
+    /// Illegal byte sequence.
     ilseq,
-    // Operation in progress.
+    /// Operation in progress.
     inprogress,
-    // Interrupted function.
+    /// Interrupted function.
     intr,
-    // Invalid argument.
+    /// Invalid argument.
     inval,
-    // I/O error.
+    /// I/O error.
     io,
-    // Socket is connected.
+    /// Socket is connected.
     isconn,
-    // Is a directory.
+    /// Is a directory.
     isdir,
-    // Too many levels of symbolic links.
+    /// Too many levels of symbolic links.
     loop,
-    // File descriptor value too large.
+    /// File descriptor value too large.
     mfile,
-    // Too many links.
+    /// Too many links.
     mlink,
-    // Message too large.
+    /// Message too large.
     msgsize,
-    // Reserved.
+    /// Reserved.
     multihop,
-    // Filename too long.
+    /// Filename too long.
     nametoolong,
-    // Network is down.
+    /// Network is down.
     netdown,
-    // Connection aborted by network.
+    /// Connection aborted by network.
     netreset,
-    // Network unreachable.
+    /// Network unreachable.
     netunreach,
-    // Too many files open in system.
+    /// Too many files open in system.
     nfile,
-    // No buffer space available.
+    /// No buffer space available.
     nobufs,
-    // No such device.
+    /// No such device.
     nodev,
-    // No such file or directory.
+    /// No such file or directory.
     noent,
-    // Executable file format error.
+    /// Executable file format error.
     noexec,
-    // No locks available.
+    /// No locks available.
     nolck,
-    // Reserved.
+    /// Reserved.
     nolink,
-    // Not enough space.
+    /// Not enough space.
     nomem,
-    // No message of the desired type.
+    /// No message of the desired type.
     nomsg,
-    // Protocol not available.
+    /// Protocol not available.
     noprotoopt,
-    // No space left on device.
+    /// No space left on device.
     nospc,
-    // Function not supported.
+    /// Function not supported.
     nosys,
-    // The socket is not connected.
+    /// The socket is not connected.
     notconn,
-    // Not a directory or a symbolic link to a directory.
+    /// Not a directory or a symbolic link to a directory.
     notdir,
-    // Directory not empty.
+    /// Directory not empty.
     notempty,
-    // State not recoverable.
+    /// State not recoverable.
     notrecoverable,
-    // Not a socket.
+    /// Not a socket.
     notsock,
-    // Not supported, or operation not supported on socket.
+    /// Not supported, or operation not supported on socket.
     notsup,
-    // Inappropriate I/O control operation.
+    /// Inappropriate I/O control operation.
     notty,
-    // No such device or address.
+    /// No such device or address.
     nxio,
-    // Value too large to be stored in data type.
+    /// Value too large to be stored in data type.
     overflow,
-    // Previous owner died.
+    /// Previous owner died.
     ownerdead,
-    // Operation not permitted.
+    /// Operation not permitted.
     perm,
-    // Broken pipe.
+    /// Broken pipe.
     pipe,
-    // Protocol error.
+    /// Protocol error.
     proto,
-    // Protocol not supported.
+    /// Protocol not supported.
     protonosupport,
-    // Protocol wrong type for socket.
+    /// Protocol wrong type for socket.
     prototype,
-    // Result too large.
+    /// Result too large.
     range,
-    // Read-only file system.
+    /// Read-only file system.
     rofs,
-    // Invalid seek.
+    /// Invalid seek.
     spipe,
-    // No such process.
+    /// No such process.
     srch,
-    // Reserved.
+    /// Reserved.
     stale,
-    // Connection timed out.
+    /// Connection timed out.
     timedout,
-    // Text file busy.
+    /// Text file busy.
     txtbsy,
-    // Cross-device link.
+    /// Cross-device link.
     xdev,
-    // Extension: Capabilities insufficient.
+    /// Extension: Capabilities insufficient.
     notcapable,
   }
 }

crates/wit-parser/tests/ui/wasi.wit.json

@@ -523,7 +523,7 @@
         "interface": 0
       },
       "docs": {
-        "contents": "Error codes returned by functions.\nNot all of these error codes are returned by the functions provided by this\nAPI/ some are used in higher-level library layers, and others are provided\nmerely for alignment with POSIX."
+        "contents": "Error codes returned by functions.\n\nNot all of these error codes are returned by the functions provided by this\nAPI/ some are used in higher-level library layers, and others are provided\nmerely for alignment with POSIX."
       }
     }
   ],