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 ```
   8 // Anything after two forward slashes is a comment
   9 NameOfClass.WithPossibleNamespace
  10    + class property
  11    - instance property
  12   ~> listened events (socket)
  13   +> listened events (class/module)
  14   -> listened events (instance)
  15   <~ dispatched events (socket)
  16   <+ dispatched events(class/module)
  17   <- dispatched events (instance)
  18   :: class method
  19    # instance method
  20
  21 Other symbols
  22   => returns
  23   #> throws
  24 [xx] optional
  25 <xx> data type
  26
  27 Recommended order: class first, then sockets, then instance. Internally:
  28 Properties, events, methods.
  29 ```
  30
  31 Or, with some examples:
  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 <Type>
  39   -instance_property <Types<Can<Be<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 <Type>) => ReturnValueType #> BadTimesException,UnknownError
  45   #update(text <String>, [options] <GlobalOptions.tOptions>) => Promise<Void>
  46   // Listened Events
  47   +>static_listener(parameters_expected <Bool>)
  48   ->instance_listener()
  49   ~>network_events(peer <Networking.Peer>)
  50   // Emitted Events
  51   <+emitted_statically(payload <StaticEventPayload>)
  52   <-emitted_by_instance(reason <String>, code <Int>)
  53   <~emitted_through_network(text <String>)
  54 ```
  55
  56 When defining function types, you may use parameter lists, returns and throws notation as well.
  57
  58 ```
  59 HypotheticalModule
  60   #transform<T>( Function<T>(payload <T>) => <T>, announce <Bool>) => <Bool>
  61 ```