Use triple-slash comments for documentation

[sunfishcode]

I propose that the Wit format use /// comments, rather than //.

Wit itself no longer has non-documentation comments, however multiple projects are looking at using Wit as a base language that they can extend with more features. For such languages, it will be desirable to be able to have both documentation and regular comments, while remaining a superset of Wit.

Using /// for documentation and // for regular comments is a common convention, found in rustdoc, doxygen, C#, Swift, and others.

In the short term, the wit tooling can continue to accept both /// and // as documentation comments, until existing Wit files are migrated. In the long term, wit tooling could reject // comments to free up their space in the grammar for derived languages.

@peterhuene @lukewagner @esoterra

[esoterra]

That's a good point, languages like claw will definitely want to A. make a distinction between doc and normal comments, B. choose to represent doc comments as /// to match common convention, and C. keep its use of WIT syntax for type and interface definitions exactly compatible.

The best way to enable this is for WIT itself to use the prefix /// for doc comments.

[lukewagner]

Yes, that's a good point. The high-order bit in #273 was removing a confusing choice by having only one form of comment, but this could be achieved just as well by having that form be ///, thereby reserving // for use in languages embedding WIT (which is popping up). So this change makes sense to me. I'm sorry I didn't spot this issue earlier to avoid the recent churn, but maybe this direction actually makes less churn overall (given that most WASI WITs have already been moved over to ///)? WDYT @alexcrichton?

[alexcrichton]

Setting aside churn for a moment, I'm not sure I understand fully how this would enable other languages to use //. It sounds like the goal is to make // not parse in a WIT file, but I also feel like I might be missing something.

As for the churn, I'd need to better understand the fate of //-in-WIT to better comment on that.

[esoterra]

The idea is to normalize on /// only for WIT doc comments and remove //.

Then languages which extend or embed WIT would be able to use the // vs. /// convention to have doc and normal comments in a way where the embedded WIT doc comments continue to be treated as doc comments.

[sunfishcode]

Concerning churn, all the Wit files I've seen are currently using /// for documentation, so the proposal here would result in less churn than converting them all to //.

[alexcrichton]

Ah ok I think I see better now. In that case the "churn" here would be that wit-parser would start to emit a warning to stdio whenever it encountered a // comment with a recommendation to use /// instead. All versions of wit-parser accept /// already so once the warning is in place for awhile we could remove parsing support.

That I do think will require some changes to be made but I think it's feasible to do.