search

WebAssembly / component-model

Repository for design and specification of the Component Model
Other
914 stars 78 forks source link

wit: Reserve doc-comment "annotation" syntax #256

Open lann opened 10 months ago

lann commented 10 months ago

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 commented 8 months ago

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