Closed lukewagner closed 7 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.)
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.
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?
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.
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
anddoc-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:
@
character, it will be annoying b/c actual comment content may want to use this (for versions, email addresses, @-mentions, etc)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)