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.
Reference
The notation allows describing objects or modules, with properties, events and methods along with their types.
// 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
Example
With this artificial example, you can see how to use it for more complex cases:
// 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>
// Function types can include parameter lists, returns and throws as well.
#transform<T>( Function<T>(payload <T>) => <T>, announce <Bool>) => <Bool>
// 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>)