component-model
component-model copied to clipboard
wit: Reserve doc-comment "annotation" syntax
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.
JSDoc annotation syntax reference: https://jsdoc.app/ (and in particular https://jsdoc.app/about-block-inline-tags)