📝 Future v1

The first offical release of Future

spec/alizarin_spec.cr

@@ -193,7 +193,7 @@ describe Future do
     ret.should eq File.read("./LICENSE")
   end
 
-  it "when a then does not resolve a value, the next then (if any) receives undefined as resolved_value" do
+  it "if a then does not resolve , later callbacks will not be executed" do
     eval_js <<-JS
       window.returned_value = undefined;
       var future = new Future(function(resolve,reject){

src/components/web_extension.cr

@@ -1,3 +1,5 @@
+require "./web_extension/**"
+
 # According to architecture of WebKit2GTK, JavaScript code runs in a separeted process called Render Process.
 # That's why extending JavaScript can not be done in the same process which manages the `WebView`.
 # Instead WebKit2GTK proposes a new way to extend JavaScript with native code called WebExtension.
@@ -38,9 +40,6 @@
 # 4. `JSCObject`
 # 5. `JSObjectUtils`
 module WebExtension
-  annotation JSCInstanceMethod; end
-  # See `JSCInstanceMethod`.
-  annotation Chainable; end
   @@uuid = ""
 
   # :nodoc:
@@ -152,23 +151,24 @@ module WebExtension
     end
   end
 
-  #Exposes a Crystal's Class so it can be used in JavaScript
+  # Exposes a Crystal's Class so it can be used in JavaScript
   #
+  # Example:
   # * webextension.cr:
-  # ```crystal
+  # ```
   # class File
   #   def initialize(p : [] of (JSCFunction | JSCObject | JSCPrimative))
   #     super(p.first.to_s)
-  #   end 
-  #   
+  #   end
+  #
   #   @[JSCInstanceMethod]
   #   def content(p)
   #     self.seek(0)
   #     self.gets_to_end
   #   end
   # end
   # JSCContext.set_value "File", WebExtension.register_class(File)
-  # 
+  #
   # ```
   # * index.js
   # ```js

src/components/web_extension/annotations.cr

@@ -0,0 +1,70 @@
+module WebExtension
+  # Alizarin allows us to create custom JavaScript classes using plain Crystal classes.
+  # All we need to do is to register our classes using `WebExtension.register_class` macro.
+  # Note that if we need to expose any method of our Crystal's class so we can call it in JavaScript later, we **must** annotate it with this annotation, `JSCInstanceMethod`.
+  #
+  # The example bellow demonstrates how to create a custom JavaScript class which allow us to read content of given file on disk.
+  # * extension.cr
+  # ```
+  # require 'alizarin'
+  # include WebExtension
+  # class File #here we do not have to construct a new class from scratch, just extend existing one.
+  #   def initialize(params : [] of JSCObject | JSCFunction | JSCPrimative)
+  #       super(params.first.to_s)
+  #   end
+  #
+  #   @[JSCInstanceMethod]
+  #   def content(p)
+  #     self.seek(0)
+  #     self.gets_to_end
+  #   end
+  # end
+  #
+  # initialize_extension do
+  #     JSCContext.set_value "File", register_class(File)
+  # end
+  # ```
+  # * index.js
+  # ```javascript
+  # var file_content = new File("./LICENSE").content();
+  # console.log(file_content);
+  # ```
+  annotation JSCInstanceMethod; end
+
+  # When a Crystal instance method is annotated with `Chainable`, it means that the method will return the instance itself instead of a `JSC::JSValue`.
+  # It does not matter what type of data the method returns, it will always return the current instance which call the method.
+  # * extension.cr
+  # ```
+  # require 'alizarin'
+  # include WebExtension
+  # class File #here we do not have to construct a new class from scratch, just extend existing one.
+  #   def initialize(params : [] of JSCObject | JSCFunction | JSCPrimative)
+  #       super(params.first.to_s)
+  #   end
+  #
+  #   @content = ""
+  #
+  #   @[JSCInstanceMethod]
+  #   @[Chainable]
+  #   def read(p)
+  #     self.seek(0)
+  #     @content = self.gets_to_end
+  #   end
+  #
+  #   @[JSCInstanceMethod]
+  #   def content(p)
+  #     @content
+  #   end
+  # end
+  #
+  # initialize_extension do
+  #     JSCContext.set_value "File", register_class(File)
+  # end
+  # ```
+  # * index.js
+  # ```javascript
+  # var file_content = new File("./LICENSE").read().content();
+  # console.log(file_content);
+  # ```
+  annotation Chainable; end
+end