component-model icon indicating copy to clipboard operation
component-model copied to clipboard

wit: Reserve doc-comment "annotation" syntax

Open lann opened this issue 2 years ago • 1 comments

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.

lann avatar Sep 27 '23 16:09 lann

JSDoc annotation syntax reference: https://jsdoc.app/ (and in particular https://jsdoc.app/about-block-inline-tags)

lann avatar Nov 21 '23 19:11 lann