X-Git-Url: https://git.r.bdr.sh/rbdr/r.bdr.sh/blobdiff_plain/bfaa66583b3210ad6da796a26f20e601c03275e4..1b09746e439b38a6e4da43c6b4785372d1aef44a:/api.gmi

diff --git a/api.gmi b/api.gmi
index d0d99ad..60cc62a 100644
--- a/api.gmi
+++ b/api.gmi
@@ -1,9 +1,11 @@
 --- title: /api.html
 --- description: API Notation
-# API Notation
+## 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
@@ -17,45 +19,38 @@ NameOfClass.WithPossibleNamespace
   <- dispatched events (instance)
   :: class method
    # instance method
-
+----
 Other symbols
   => returns
   #> throws
 [xx] optional
 <xx> data type
-
-Recommended order: class first, then sockets, then instance. Internally:
-Properties, events, methods.
 ```
 
-Or, with some examples:
+## 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>>>>
+  +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 <Type>) => ReturnValueType #> BadTimesException,UnknownError
-  #update(text <String>, [options] <GlobalOptions.tOptions>) => Promise<Void>
+  ::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 <Bool>)
+  +>static_listener(parameters_expected &lt;Bool>)
   ->instance_listener()
-  ~>network_events(peer <Networking.Peer>)
+  ~>network_events(peer &lt;Networking.Peer>)
   // Emitted Events
-  <+emitted_statically(payload <StaticEventPayload>)
-  <-emitted_by_instance(reason <String>, code <Int>)
-  <~emitted_through_network(text <String>)
-```
-
-When defining function types, you may use parameter lists, returns and throws notation as well.
-
-```
-HypotheticalModule
-  #transform<T>( Function<T>(payload <T>) => <T>, announce <Bool>) => <Bool>
+  &lt;+emitted_statically(payload &lt;StaticEventPayload>)
+  &lt;-emitted_by_instance(reason &lt;String>, code &lt;Int>)
+  &lt;~emitted_through_network(text &lt;String>)
 ```