diff --git a/crates/wit-parser/src/ast/resolve.rs b/crates/wit-parser/src/ast/resolve.rs index b1c9d08d0b..49c63ffdd4 100644 --- a/crates/wit-parser/src/ast/resolve.rs +++ b/crates/wit-parser/src/ast/resolve.rs @@ -1280,10 +1280,11 @@ impl<'a> Resolver<'a> { fn docs(&mut self, doc: &super::Docs<'_>) -> Docs { let mut lines = vec![]; for doc in doc.docs.iter() { - if let Some(doc) = doc.strip_prefix("/**") { - lines.push(doc.strip_suffix("*/").unwrap().trim()); - } else { - lines.push(doc.trim_start_matches('/').trim()); + // Comments which are not doc-comments are silently ignored + if let Some(doc) = doc.strip_prefix("/// ") { + lines.push(doc.trim_end()); + } else if doc == "///\n" { + lines.push(""); } } let contents = if lines.is_empty() { diff --git a/crates/wit-parser/tests/ui/comments.wit b/crates/wit-parser/tests/ui/comments.wit index 46545453de..ffcb398a17 100644 --- a/crates/wit-parser/tests/ui/comments.wit +++ b/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; diff --git a/crates/wit-parser/tests/ui/comments.wit.json b/crates/wit-parser/tests/ui/comments.wit.json index f2a04f9d39..0c9003a28f 100644 --- a/crates/wit-parser/tests/ui/comments.wit.json +++ b/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 } diff --git a/crates/wit-parser/tests/ui/types.wit b/crates/wit-parser/tests/ui/types.wit index bb391f91b1..f21b0119dc 100644 --- a/crates/wit-parser/tests/ui/types.wit +++ b/crates/wit-parser/tests/ui/types.wit @@ -54,7 +54,7 @@ interface types { type t52 = future; type t53 = future; - // type order doesn't matter + /// type order doesn't matter type foo = bar; type bar = u32; } diff --git a/crates/wit-parser/tests/ui/wasi.wit b/crates/wit-parser/tests/ui/wasi.wit index cf084a3fe8..d22e144dd1 100644 --- a/crates/wit-parser/tests/ui/wasi.wit +++ b/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, } } diff --git a/crates/wit-parser/tests/ui/wasi.wit.json b/crates/wit-parser/tests/ui/wasi.wit.json index e784fbd207..5ca0d69889 100644 --- a/crates/wit-parser/tests/ui/wasi.wit.json +++ b/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." } } ],