Update reference/api_notation.md

1 files changed, 53 insertions, 0 deletions

diff --git a/reference/api_notation.md b/reference/api_notation.md
new file mode 100644
index 0000000..f4d7c11
--- /dev/null
+++ b/reference/api_notation.md
@@ -0,0 +1,53 @@
+# API Notation
+
+The following document attempts to define a legend for easy specification of APIs for components. Any suggestions to improve are welcome.
+
+```
+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.
+
+// 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.
+
+```
+EventHypotheticalClass
+  +>AnotherClass<+staticEventToListen(eventData <PredefinedObject>)
+  <+staticEventDispatched(someData <SomeData>)
+  ~>listenedSocketEvent(eventData <SomeObject>)
+  <~dispatchedSocketEvent(eventData <BlaBla>)
+  ->AnotherClass<-instanceEventToListen(eventData <Object>)
+  <-instanceEventDispatched(specificDataType <DefinedObject>)
+```