| | 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 <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 | // Function types can include parameter lists, returns and throws as well. |
| | 47 | #transform<T>( Function<T>(payload <T>) => <T>, announce <Bool>) => <Bool> |
| | 48 | // Listened Events |
| | 49 | +>static_listener(parameters_expected <Bool>) |
| | 50 | ->instance_listener() |
| | 51 | ~>network_events(peer <Networking.Peer>) |
| | 52 | // Emitted Events |
| | 53 | <+emitted_statically(payload <StaticEventPayload>) |
| | 54 | <-emitted_by_instance(reason <String>, code <Int>) |
| | 55 | <~emitted_through_network(text <String>) |
| | 56 | ``` |
git.r.bdr.sh / rbdr / r.bdr.sh / blame_incremental