git.r.bdr.sh - rbdr/r.bdr.sh/blob - api.gmi

   1 --- title: /api.html
   2 --- description: API Notation
   3 ## API Notation
   4
   5 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.
   6
   7 ## Reference
   8 The notation allows describing objects or modules, with properties, events and methods along with their types.
   9 ```
  10 // Anything after two forward slashes is a comment
  11 NameOfClass.WithPossibleNamespace
  12    + class property
  13    - instance property
  14   ~> listened events (socket)
  15   +> listened events (class/module)
  16   -> listened events (instance)
  17   <~ dispatched events (socket)
  18   <+ dispatched events(class/module)
  19   <- dispatched events (instance)
  20   :: class method
  21    # instance method
  22 ----
  23 Other symbols
  24   => returns
  25   #> throws
  26 [xx] optional
  27 <xx> data type
  28 ```
  29
  30 ## Example
  31 With this artificial example, you can see how to use it for more complex cases:
  32
  33 ```
  34 // Definitions start with object / module / class names, with namespaces
  35 // separated by periods. Types are marked between angular brackets.
  36 Definitions.Models.Post
  37   // Properties.
  38   +static_property &lt;Type>
  39   -instance_property &lt;Types&lt;Can&lt;Be&lt;Nested>>>>
  40   // Methods. Parameters are listed in parentheses, and comma separated.
  41   // Optional values are inside brackets
  42   // => defines return values
  43   // #> defines thrown exceptions, can be comma separated.
  44   ::static_methods(parameter_label &lt;Type>) => ReturnValueType #> BadTimesException,UnknownError
  45   #update(text &lt;String>, [options] &lt;GlobalOptions.tOptions>) => Promise&lt;Void>
  46   // Function types can include parameter lists, returns and throws as well.
  47   #transform&lt;T>( Function&lt;T>(payload &lt;T>) => &lt;T>, announce &lt;Bool>) => &lt;Bool>
  48   // Listened Events
  49   +>static_listener(parameters_expected &lt;Bool>)
  50   ->instance_listener()
  51   ~>network_events(peer &lt;Networking.Peer>)
  52   // Emitted Events
  53   &lt;+emitted_statically(payload &lt;StaticEventPayload>)
  54   &lt;-emitted_by_instance(reason &lt;String>, code &lt;Int>)
  55   &lt;~emitted_through_network(text &lt;String>)
  56 ```