Update API Notation

[rbdr/r.bdr.sh] / api.gmi

--- title: /api.html
--- description: API Notation
# API Notation

API Notation is a language-agnostic notation to share the public API of components in code. It was created to standardize software specification documents in teams that need to review code across several languages.

The notation consists of one or more `definitions`, and `comments`

```
// Definitions start with object / module / class names, with namespaces
// separated by periods. Types are marked between angular brackets.
Definitions.Models.Post
  // Properties.
  +static_property <Type>
  -instance_property <Types<Can<Be<Nested>>>>
  // Methods. Parameters are listed in parentheses, and comma separated.
  // Optional values are inside brackets
  // => defines return values
  // #> defines thrown exceptions, can be comma separated.
  ::static_methods(parameter_label <Type>) => ReturnValueType #> BadTimesException,UnknownError
  #update(text <String>, [options] <GlobalOptions.tOptions>) => Promise<Void>
  // Listened Events
  +>static_listener(parameters_expected <Bool>)
  ->instance_listener()
  ~>network_events(peer <Networking.Peer>)
  // Emitted Events
  <+emitted_statically(payload <StaticEventPayload>)
  <-emitted_by_instance(reason <String>, code <Int>)
  <~emitted_through_network(text <String>)
```

When defining function types, you may use parameter lists, returns and throws notation as well.

```
HypotheticalModule
  #transform<T>( Function<T>(payload <T>) => <T>, announce <Bool>) => <Bool>
```