WebAssembly / WebAssembly/component-model

Use triple-slash comments for documentation

Open
#286 6 comments 5 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.