Consider removing separate doc-comment form from WIT #273

This question was initially raised and discussed in wasm-tools#1206, but I think it's useful to discuss again in a standards context and also capture newer ideas and discussions since then.

So, currently WIT has two forms of comments, captured by the comment and doc-comment productions in WIT.md, with the idea being that only the latter gets rendered into generated documentation. This is common in programming languages, so a reasonable starting point in the initial design. However, WIT is an IDL, not a regular programming language, and so it's worth asking whether the additional complexity of having 2 forms of comments in an IDL is justified by use cases. As a WASI WIT author and reviewer, I've already had a few cases over the last few months of having to comment "this should be a doc-comment", which causes churn and wastes time. My current operating mode is just to say that everything should be a doc-comment and to pretend that the // form doesn't exist, which seems like a red flag.

In considering the use cases for having non-doc-comments, the theme seems to be that there is some information that you want to put in the .wit but you don't want to show to "usual" readers of the rendered docs. But I think these sorts of use cases can naturally fall out of a more general change we want to make anyways, which is to add something in the space of Javadoc/JSDoc comments, having particular tags like @todo or @editorial that can be hidden by default when rendering docs.

Motivated by #256 we thought a bit about how we might "reserve" some syntax for these @ tags, but:

• if we simply rule out the @ character, it will be annoying b/c actual comment content may want to use this (for versions, email addresses, @-mentions, etc)
• if we try to carve out a more-targeted @ tag syntax, it will end up just adding an under-specified syntax that I worry would lead to mutually-incompatible implementations in the interim

Instead, I propose we simply delete the doc-comment form right now and follow on quickly next year with a proper @ tag syntax that can enable rendered documentation (co-designing it with the actual doc-rendering tools we'll be building in any case).

(cc @lann @alexcrichton @tschneidereit)