black and white

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

diff --git a/api.gmi b/api.gmi
index d0d99ad5285587383853068ca6e3e386174135ec..60cc62a102cb1bfcb08364ed956325fa8cf7d147 100644 (file)
--- a/api.gmi
+++ b/api.gmi
@@ -1,9 +1,11 @@
 --- 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.
 

+## 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
 ```
 // Anything after two forward slashes is a comment
 NameOfClass.WithPossibleNamespace


@@ -17,45 +19,38 @@ NameOfClass.WithPossibleNamespace
   <- dispatched events (instance)
   :: class method
    # instance method
   <- dispatched events (instance)
   :: class method
    # instance method

-
+----

 Other symbols
   => returns
   #> throws
 [xx] optional
 <xx> data type
 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.
 
 ```
 // 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>)

 ```
 ```