@doc and @meta annotations

[dmitrii-ubskii]

Product change and motivation

We implement @doc("docstring") and @meta("key", "value") schema annotations. These annotations can be attached to types and capabilities i.e. owns, plays, relates, and sub:

define
entity person @doc("this represents an individual client") @meta("icon", ":silhouette.png"),
  owns name @doc("full name including title");

match
  $x isa client;
  let $x_icon = get_meta("icon", $t); # get each client with a UI display icon hint

These annotations can also be attached to function definitions. They go at the end of the signature, before the colon introducing the body of the function:

define
fun get_random_number() -> integer
    @doc("chosen by a fair dice roll"):
match
  let $rand = 4;
return first $rand;

Implementation

[flyingsilverfin]

Oh fun can we dissolve the core-specific IR for these now?

[dmitrii-ubskii]

No, the Meta category carries a StringLiteral in typeql but a parsed unescaped String in core.

[flyingsilverfin]

so how do we expect to write this?

define
fun get_name($p: person) -> { name}
    @doc("..."):
  match $p has name $name;
  return { $name };

?

[flyingsilverfin]

Approved w comments