Make lis small

[rbdr/r.bdr.sh] / api.gmi

diff --git a/api.gmi b/api.gmi
index 3e4860767fe0f51866e7c4ca3d7bf366db24eb29..60cc62a102cb1bfcb08364ed956325fa8cf7d147 100644 (file)
--- a/api.gmi
+++ b/api.gmi
@@ -1,10 +1,13 @@
 --- title: /api.html
 --- description: API Notation
-# API Notation
+## API Notation
 
-The following document attempts to define a legend for easy specification of APIs for components. Any suggestions to improve are welcome.
+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
@@ -16,40 +19,38 @@ NameOfClass.WithPossibleNamespace
   <- dispatched events (instance)
   :: class method
    # instance method
-   
+----
 Other symbols
   => returns
-->() callback return
+  #> throws
 [xx] optional
 <xx> data type
-
-Recommended order: class first, then sockets, then instance. Internally: Properties, events, methods.
-
-// Anything after two forward slashes is a comment
-```
-
-Here's an example of usage
-
-```
-HypotheticalModule
-  +staticProperty <String>
-  +anotherStaticProperty <Boolean>
-  ::toggleAnotherStaticProperty()
-  ::setStaticProperty(newValue <String>)
-  -instanceProperty <Number>
-  -anotherInstanceProperty <String>
-  #instanceMethodSync([optionalParameter]<Boolean>) => resultOfCall <String>
-  #instanceMethodAsync(someValue <Number>, [callback] <Function>) ->(error <String|null>, result <Number|null>)
 ```
 
-Here's another example but with events.
+## Example
+With this artificial example, you can see how to use it for more complex cases:
 
 ```
-EventHypotheticalClass
-  +>AnotherClass<+staticEventToListen(eventData <PredefinedObject>)
-  <+staticEventDispatched(someData <SomeData>)
-  ~>listenedSocketEvent(eventData <SomeObject>)
-  <~dispatchedSocketEvent(eventData <BlaBla>)
-  ->AnotherClass<-instanceEventToListen(eventData <Object>)
-  <-instanceEventDispatched(specificDataType <DefinedObject>)
+// Definitions start with object / module / class names, with namespaces
+// separated by periods. Types are marked between angular brackets.
+Definitions.Models.Post
+  // Properties.
+  +static_property &lt;Type>
+  -instance_property &lt;Types&lt;Can&lt;Be&lt;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 &lt;Type>) => ReturnValueType #> BadTimesException,UnknownError
+  #update(text &lt;String>, [options] &lt;GlobalOptions.tOptions>) => Promise&lt;Void>
+  // Function types can include parameter lists, returns and throws as well.
+  #transform&lt;T>( Function&lt;T>(payload &lt;T>) => &lt;T>, announce &lt;Bool>) => &lt;Bool>
+  // Listened Events
+  +>static_listener(parameters_expected &lt;Bool>)
+  ->instance_listener()
+  ~>network_events(peer &lt;Networking.Peer>)
+  // Emitted Events
+  &lt;+emitted_statically(payload &lt;StaticEventPayload>)
+  &lt;-emitted_by_instance(reason &lt;String>, code &lt;Int>)
+  &lt;~emitted_through_network(text &lt;String>)
 ```