git.r.bdr.sh - rbdr/txt/blob - reference/api_notation.md

   1 # API Notation
   2
   3 The following document attempts to define a legend for easy specification of APIs for components. Any suggestions to improve are welcome.
   4
   5 ```
   6 NameOfClass.WithPossibleNamespace
   7    + class property
   8    - instance property
   9   ~> listened events (socket)
  10   +> listened events (class/module)
  11   -> listened events (instance)
  12   <~ dispatched events (socket)
  13   <+ dispatched events(class/module)
  14   <- dispatched events (instance)
  15   :: class method
  16    # instance method
  17
  18 Other symbols
  19   => returns
  20 ->() callback return
  21 [xx] optional
  22 <xx> data type
  23
  24 Recommended order: class first, then sockets, then instance. Internally: Properties, events, methods.
  25
  26 // Anything after two forward slashes is a comment
  27 ```
  28
  29 Here's an example of usage
  30
  31 ```
  32 HypotheticalModule
  33   +staticProperty <String>
  34   +anotherStaticProperty <Boolean>
  35   ::toggleAnotherStaticProperty()
  36   ::setStaticProperty(newValue <String>)
  37   -instanceProperty <Number>
  38   -anotherInstanceProperty <String>
  39   #instanceMethodSync([optionalParameter]<Boolean>) => resultOfCall <String>
  40   #instanceMethodAsync(someValue <Number>, [callback] <Function>) ->(error <String|null>, result <Number|null>)
  41 ```
  42
  43 Here's another example but with events.
  44
  45 ```
  46 EventHypotheticalClass
  47   +>AnotherClass<+staticEventToListen(eventData <PredefinedObject>)
  48   <+staticEventDispatched(someData <SomeData>)
  49   ~>listenedSocketEvent(eventData <SomeObject>)
  50   <~dispatchedSocketEvent(eventData <BlaBla>)
  51   ->AnotherClass<-instanceEventToListen(eventData <Object>)
  52   <-instanceEventDispatched(specificDataType <DefinedObject>)
  53 ```