WebAssembly / component-model

Repository for design and specification of the Component Model
Other
914 stars 78 forks source link

Consider removing separate doc-comment form from WIT #273

Closed lukewagner closed 7 months ago

lukewagner commented 8 months ago

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:

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)

lann commented 8 months ago

One other option for doc comment annotations would be to specify a pattern that we think is likely to be used and just emit warnings that e.g. "this may break later" as a sort of "soft reservation" of the syntax. (But I'm not opposed to doing nothing either.)

lukewagner commented 8 months ago

Maybe for starters I'll just delete the production and then if it takes us too long to make a "real" proposal, we could go with your "soft reservation" idea.

rylev commented 7 months ago

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.

I'm confused - you've noted that you have been bothered by needing to ensure that someone converts a non-doc comment to a doc comment but your proposal seems to be keeping this status quo. If we remove doc comments in favor of a @-based extension for "enabl[ing] rendered documentation" would we not effectively be keeping the status quo (comments that are conditionally rendered or not) but with a more verbose and awkward syntax?

lukewagner commented 7 months ago

The idea is that the @ isn't necessary for the comments to show up in docs, everything shows up (just like with ///); the @s are there to provide refinements for controlling presentation, formatting, linking, etc.