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 The notation consists of one or more `definitions`, and `comments`
   8
   9 ```
  10 // Definitions start with object / module / class names, with namespaces
  11 // separated by periods. Types are marked between angular brackets.
  12 Definitions.Models.Post
  13   // Properties.
  14   +static_property <Type>
  15   -instance_property <Types<Can<Be<Nested>>>>
  16   // Methods. Parameters are listed in parentheses, and comma separated.
  17   // Optional values are inside brackets
  18   // => defines return values
  19   // #> defines thrown exceptions, can be comma separated.
  20   ::static_methods(parameter_label <Type>) => ReturnValueType #> BadTimesException,UnknownError
  21   #update(text <String>, [options] <GlobalOptions.tOptions>) => Promise<Void>
  22   // Listened Events
  23   +>static_listener(parameters_expected <Bool>)
  24   ->instance_listener()
  25   ~>network_events(peer <Networking.Peer>)
  26   // Emitted Events
  27   <+emitted_statically(payload <StaticEventPayload>)
  28   <-emitted_by_instance(reason <String>, code <Int>)
  29   <~emitted_through_network(text <String>)
  30 ```
  31
  32 When defining function types, you may use parameter lists, returns and throws notation as well.
  33
  34 ```
  35 HypotheticalModule
  36   #transform<T>( Function<T>(payload <T>) => <T>, announce <Bool>) => <Bool>
  37 ```