WebAssembly / WebAssembly/component-model

wit: Reserve doc-comment "annotation" syntax

Open
#256 1 comment 6 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

In order to allow for future strict parsing of doc comment annotations, we could reserve a pattern for annotations now (without necessarily defining any valid annotations).

One common approach is @annotations, used by JSDoc, Javadoc, and others. An example of how that could look in WIT (once specified):

/// Runs the command.
/// @param args - A list of command line arguments.
/// @returns `ok` if the command completes successfully.
export run: func(args: list<string>) -> result

We could reserve the pattern e.g. "@ at the start but not middle of a word" (regexp /\b@[a-z]/) or something similar.

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 with the WIT doc-comment syntax and the proposed /\b@[a-z]/ pattern. Compare the possible word-boundary behavior and decide how annotation-like text should be recognized without defining valid annotations. Done means the reserved pattern and its scope are specified clearly enough for future strict parsing.

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
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.