Add control

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

diff --git a/api.gmi b/api.gmi
index 62974d0b238bab3944c627c7b8dca49d648c14f2..60cc62a102cb1bfcb08364ed956325fa8cf7d147 100644 (file)
--- a/api.gmi
+++ b/api.gmi
@@ -1,37 +1,56 @@
 --- title: /api.html
 --- description: API Notation
 --- 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.
 
 
 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.
 

-The notation consists of one or more `definitions`, and `comments`
+## 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.
 
 ```
 // 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.
   // 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
   // Listened Events

-  +>static_listener(parameters_expected <Bool>)
+  +>static_listener(parameters_expected &lt;Bool>)

   ->instance_listener()
   ->instance_listener()

-  ~>network_events(peer <Networking.Peer>)
+  ~>network_events(peer &lt;Networking.Peer>)

   // Emitted Events
   // 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>)

 ```
 ```