Add dsk learning

[rbdr/txt] / reference / api_notation.md

# 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>)
```