Columnize

[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.

```
// Anything after two forward slashes is a comment
NameOfClass.WithPossibleNamespace
   + class property
   - instance property
  ~> listened events (socket)
  +> listened events (class/module)
  -> listened events (instance)
  <~ dispatched events (socket)
  <+ dispatched events(class/module)
  <- dispatched events (instance)
  :: class method
   # instance method

Other symbols
  => returns
  #> throws
[xx] optional
<xx> data type

Recommended order: class first, then sockets, then instance. Internally:
Properties, events, methods.
```

Or, with some examples:

```
// 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>
```