WebAssembly / WebAssembly/component-model
Use triple-slash comments for documentation
Nobody has claimed this yet.
- Dominant language
- WebAssembly
- Stars
- 1.4k
- Forks
- 130
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 15
Description
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
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the proposal and its linked component-model issue 273, then locate the Wit grammar and comment-handling entry points in the repository. Determine whether both /// and // should remain accepted during migration and what the long-term grammar should reject. Done requires an agreed syntax policy and corresponding tooling changes, but no files or tests are named in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- wasm
- Domain
- compilers
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100