From: Ruben Beltran del Rio <redacted>
Date: Wed, 4 Oct 2023 15:32:55 +0000 (+0200)
Subject: Update API Notation
X-Git-Url: https://git.r.bdr.sh/rbdr/r.bdr.sh/commitdiff_plain/12629849c4b985f18f27310273cc1168175753ca

Update API Notation
---

diff --git a/api.gmi b/api.gmi
index 3e48607..62974d0 100644
--- a/api.gmi
+++ b/api.gmi
@@ -2,54 +2,36 @@
 --- description: 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.
 
-```
-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
-->() callback return
-[xx] optional
-<xx> data type
-
-Recommended order: class first, then sockets, then instance. Internally: Properties, events, methods.
+The notation consists of one or more `definitions`, and `comments`
 
-// 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>)
+// 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>
+  // 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>)
 ```
 
-Here's another example but with events.
+When defining function types, you may use parameter lists, returns and throws notation as well.
 
 ```
-EventHypotheticalClass
-  +>AnotherClass<+staticEventToListen(eventData <PredefinedObject>)
-  <+staticEventDispatched(someData <SomeData>)
-  ~>listenedSocketEvent(eventData <SomeObject>)
-  <~dispatchedSocketEvent(eventData <BlaBla>)
-  ->AnotherClass<-instanceEventToListen(eventData <Object>)
-  <-instanceEventDispatched(specificDataType <DefinedObject>)
+HypotheticalModule
+  #transform<T>( Function<T>(payload <T>) => <T>, announce <Bool>) => <Bool>
 ```
diff --git a/index.gmi b/index.gmi
index 45aab47..7c5b996 100644
--- a/index.gmi
+++ b/index.gmi
@@ -53,9 +53,13 @@ A UI Plugin for quicksilver
 
 ### API Notation
 
-A syntax for notating component APIs in a way that's easy to embed in text documents.
+A syntax for notating component APIs in text documents. We provide a tree-sitter parser and a neovim plugin.
 
 => ./api.gmi API Notation definition
+=> https://git.sr.ht/~rbdr/tree-sitter-api-notation tree-sitter parser and neovim plugin.
+
+Older versions of the plugin exist for other editors, though they support an older version of the notation definition.
+
 => https://git.sr.ht/~rbdr/api-notation.vim Syntax for vim
 => https://git.sr.ht/~rbdr/api-notation.vscode Syntax for vscode
 => https://git.sr.ht/~rbdr/api-notation-atom Syntax for atom