You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
wit: why are there both regular comments and doc comments #1206
This was basically me taking a leaf out of Rust's book with // comments and /// doc-comments. In retrospect though WIT isn't a programming language so almost all comments are going to be documentation-related, so it might make sense to remove this paradigm and simply consider all comments preceding an item documentation comments. From a tooling perspective though that also feels a bit odd because then there's no way to have a comment that doesn't show up in documentation, so I could sort of go either way on this.
Changing this though wouldn't be too hard, it'd be to remove any mention of doc comments and parsing all comments as doc comments. For rending we'd probably strip all leading / characters so /// wouldn't render as a bunch of /-prefixed strings.
I agree that since wit isn't a programming language, all comments are documentation :) I think we should change the spec to just // comments and let our implementation strip the third / out for now, and maybe warn that the old syntax will go away at some point?
I think it's extremely valuable to have both doc comments and normal ones, even in an IDL: same as in Real Programs, it's useful to document decisions about the structure of the interface, or note aspects of the layout/ordering of things, etc, without those showing up in (interface-)user-facing documentation.
What would we gain by that? I would hope that everyone is using editors that just prefix the next line with the right token when pressing enter in a comment block?
I'd be hesitant to draw too much of a conclusion from the original state of wasi-http's //-commented source in the sense what WIT is still quite "early days" and while confusion warrants consideration it doesn't necessarily require changing. Mostly in that I consider it a significant data point, but not the sole determining factor.
For example in my experience it's relatively rare to read docs (about WIT syntax in this case) and instead code is copied and/or modified from elsewhere. By the point we have folks doing this in the future I'd expect that there'd be a good number of WASI WITs to model from such that the precise choice of syntax won't really matter all that much as everyone will copy something else and editors, as Till mentions, will take care of the rest.
I personally lean towards camp "useful to have two forms", but not strongly so, myself.
I too am fine with the status quo, but don't care too much about the actual style. I think the ability to add both doc comments (critical for those using generated code from the interface) and normal comments to add context for those working on defining the interface is most important to me
Given the discussion at yesterday's component model meeting and this issue I'm going to close this as the general sentiment is to keep the split between doc/not comments for now. There's still bits to discuss like WebAssembly/component-model#256 so I'll close this largely in favor of that.
Activity
alexcrichton commentedon Sep 18, 2023
This was basically me taking a leaf out of Rust's book with
//comments and///doc-comments. In retrospect though WIT isn't a programming language so almost all comments are going to be documentation-related, so it might make sense to remove this paradigm and simply consider all comments preceding an item documentation comments. From a tooling perspective though that also feels a bit odd because then there's no way to have a comment that doesn't show up in documentation, so I could sort of go either way on this.Changing this though wouldn't be too hard, it'd be to remove any mention of doc comments and parsing all comments as doc comments. For rending we'd probably strip all leading
/characters so///wouldn't render as a bunch of/-prefixed strings.pchickey commentedon Sep 18, 2023
I agree that since wit isn't a programming language, all comments are documentation :) I think we should change the spec to just
//comments and let our implementation strip the third/out for now, and maybe warn that the old syntax will go away at some point?tschneidereit commentedon Sep 18, 2023
I think it's extremely valuable to have both doc comments and normal ones, even in an IDL: same as in Real Programs, it's useful to document decisions about the structure of the interface, or note aspects of the layout/ordering of things, etc, without those showing up in (interface-)user-facing documentation.
lann commentedon Sep 19, 2023
We could invert the usual relationship and make e.g.
//# line//*# block */comments "ignored comments".edit: to clarify,
// this would be a doc commentand//# this would nottschneidereit commentedon Sep 19, 2023
What would we gain by that? I would hope that everyone is using editors that just prefix the next line with the right token when pressing
enterin a comment block?lann commentedon Sep 19, 2023
It would just make doc-comments the syntactic default so that authors don't accidentally use non-doc comments where doc comments are intended.
alexcrichton commentedon Sep 19, 2023
I'd be hesitant to draw too much of a conclusion from the original state of wasi-http's
//-commented source in the sense what WIT is still quite "early days" and while confusion warrants consideration it doesn't necessarily require changing. Mostly in that I consider it a significant data point, but not the sole determining factor.For example in my experience it's relatively rare to read docs (about WIT syntax in this case) and instead code is copied and/or modified from elsewhere. By the point we have folks doing this in the future I'd expect that there'd be a good number of WASI WITs to model from such that the precise choice of syntax won't really matter all that much as everyone will copy something else and editors, as Till mentions, will take care of the rest.
I personally lean towards camp "useful to have two forms", but not strongly so, myself.
lann commentedon Sep 19, 2023
FWIW I'm fine with the status quo too; just giving another option in the context of this issue.
eduardomourar commentedon Sep 27, 2023
I would be in favor for doc comments. As it has been done in other IDLs (e.g. Smithy).
lann commentedon Sep 27, 2023
Relatedly: WebAssembly/component-model#256
thomastaylor312 commentedon Sep 27, 2023
I too am fine with the status quo, but don't care too much about the actual style. I think the ability to add both doc comments (critical for those using generated code from the interface) and normal comments to add context for those working on defining the interface is most important to me
alexcrichton commentedon Sep 28, 2023
Given the discussion at yesterday's component model meeting and this issue I'm going to close this as the general sentiment is to keep the split between doc/not comments for now. There's still bits to discuss like WebAssembly/component-model#256 so I'll close this largely in favor of that.