Merge pull request #64 from trlste/patch-1

Update documentation

Author: yulingtianxia

README.md

@@ -1,35 +1,109 @@
-# dart_native
+# Dart_Native
 
-Write native code using Dart. This package liberates you from native code and low performance channel.
+Dart_Native operates as both a code generator tool and a bridge to communicate between Dart and native APIs.
 
-Still under development!!! 
+Replaces the low-performing Flutter channel with faster and more concise code.
+
+* Under development
 
 [![pub package](https://img.shields.io/pub/v/dart_native.svg)](https://pub.dev/packages/dart_native)
 [![Build Status](https://travis-ci.org/dart-native/dart_native.svg?branch=master)](https://travis-ci.org/dart-native/dart_native)
 
-This is the blue part(DartNative Bridge) in the picture below:
+This package is the blue part(DartNative Bridge):
 
 ![](images/dartnative.png)
 
-## 📲 Requirement
+## Requirements
 
-| DartNative Version | Requirements |
+| Dart_Native Version | Requirements |
 | --- | --- |
 | 0.3.0 | Flutter 1.20.0 (Dart 2.9.1) |
 | 0.2.0 | Flutter 1.12.13 (Dart 2.7) |
 
-## 🌟 Feature
+## Supported Platforms
+
+iOS & Android
+
+## Usage
+
+1. Add ```dart_native``` to dependencies and ```build_runner``` to dev_dependencies.
 
-- [x] Support iOS & Android platform.
-- [x] Sync/Async channel with high performance.
-- [x] Generate Dart bridging code from native code.
-- [x] Automatic object marshalling between Dart and native.
+2. Generate Dart wrapper code with [@dartnative/codegen](https://www.npmjs.com/package/@dartnative/codegen) or write Dart code manually.
 
-## 🔮 Getting Started
+3. Generate code for automatic type conversion using [dart_native_gen](https://pub.dev/packages/dart_native_gen) with the following steps (3.1-3.3):
+
+   3.1 Annotate a Dart wrapper class with `@native`.
+    ```dart
+    @native
+    class RuntimeSon extends RuntimeStub {
+      RuntimeSon([Class isa]) : super(Class('RuntimeSon'));
+      RuntimeSon.fromPointer(Pointer<Void> ptr) : super.fromPointer(ptr);
+    }
+    ```
+  
+   3.2 Annotate your own entry (such as`main()`) with `@nativeRoot`.
+
+    ```dart
+    @nativeRoot
+    void main() {
+      runApp(App());
+    }
+    ```
+
+    3.3 Run  
+    ```bash 
+    flutter packages pub run build_runner build --delete-conflicting-outputs 
+    ```
+    to generate files into your source directory.
+
+    Note: we recommend running `clean` first:
+
+    ```bash
+    flutter packages pub run build_runner clean
+    ```
+
+4. Call autogenerated function in `<generated-name>.dn.dart` in 3.3. The function name is determined by `name` in `pubspec.yaml`.
+
+    ```dart
+    @nativeRoot
+    void main() {
+      // Function name is generated by name in pubspec.yaml.
+      runDartNativeExample(); 
+      runApp(App());
+    }
+    ```
 
+## Features
+
+### High-performance synchronous & asynchronous channeling
+
+Dart_Native costs significantly less time than the Flutter channel and supports both synchronous and asynchronous channeling. A comparison of two native channeling tasks using Flutter channel and Dart_Native is shown below. 
+
+Both tasks were executed 10,000 times in the same environment using either Flutter channel or Dart_Native:
+
+| Task | Total time cost (ms) (Channel/Dart_Native) | Channeling time cost (ms) (Channel/Dart_Native) |
+| --- | --- | --- |
+| Checking if an app needs to be installed | 5202/4166 | 919/99  |
+| Logging | 2480/2024 | 1075/432 |
+
+
+### Autogenerate succinct bridging code
+
+Dart_Native supports automatic type conversion so its bridging code is shorter & simpler than the Flutter channel.
+
+A comparison of the task of "checking if an app needs to be installed" is shown below:
+
+| | # of lines of bridging code | Coding complexity |
+| --- | --- | --- |
+| Dart_Native | Dart 1 + Native 1 | Autogenerated code returns BOOL directly |
+| Channel | Dart 15 + Native 30 | Needs to manually define return format, convert INT to BOOL, determine channel & methodName |
+
+### Automatic object marshalling between Dart and native
+
+## Examples
 ##### iOS:
 
-Dart code:
+Dart code (generated):
 
 ```dart
 // new Objective-C object.
@@ -46,7 +120,7 @@ CGRect rect = stub.fooCGRect(CGRect(4, 3, 2, 1));
 print(rect);
 
 ```
-Objective-C code:
+Corresponding Objective-C code:
 
 ```objc
 typedef int(^BarBlock)(NSObject *a);
@@ -59,11 +133,11 @@ typedef int(^BarBlock)(NSObject *a);
 @end
 ```
 
-More ios example see: [ios_unit_test.dart](/dart_native/example/lib/ios/unit_test.dart)
+More iOS examples see: [ios_unit_test.dart](/dart_native/example/lib/ios/unit_test.dart)
 
 ##### Android:
 
-Dart code:
+Dart code (generated):
 ```dart
 // new Java object.
 RuntimeStub stub = RuntimeStub();
@@ -75,7 +149,7 @@ List list = stub.getList([1, 2, 3, 4]);
 stub.setDelegateListener(DelegateStub());
 
 ```
-Java code:
+Corresponding Java code:
 
 ```java
 public class RuntimeStub {
@@ -92,15 +166,15 @@ public class RuntimeStub {
     }
 }
 ```
-More android example see: [android_unit_test.dart](/dart_native/example/lib/android/unit_test.dart)
-## 📚 Document
+More android examples see: [android_unit_test.dart](/dart_native/example/lib/android/unit_test.dart)
+## Documentation
 
 ### Readme
 
 1. [dart_native README.md](/dart_native/README.md)
 2. [dart_native_gen README.md](/dart_native_gen/README.md)
 
-### Blog
+### Further reading
 
 - [告别 Flutter Channel，调用 Native API 仅需一行代码！](http://yulingtianxia.com/blog/2020/06/25/Codegen-for-DartNative/)
 - [如何实现一行命令自动生成 Flutter 插件](http://yulingtianxia.com/blog/2020/07/25/How-to-Implement-Codegen/)
@@ -112,23 +186,21 @@ More android example see: [android_unit_test.dart](/dart_native/example/lib/andr
 - [在 Flutter 中玩转 Objective-C Block](http://yulingtianxia.com/blog/2020/03/28/Using-Objective-C-Block-in-Flutter/)
 - [Passing Out Parameter in DartNative](http://yulingtianxia.com/blog/2020/04/25/Passing-Out-Parameter-in-DartNative/)
 
-## 🐒 Q&A
+## FAQs
 
 Q: Failed to lookup symbol (dlsym(RTLD_DEFAULT, InitDartApiDL): symbol not found) on iOS archive.
 
-There are two Workarounds:
-
-1. Use dynamic library: Add `use_frameworks!` in Podfile.
-2. Select Target Runner -> Build Settings -> Strip Style -> change from "All
-Symbols" to "Non-Global Symbols"
+A: Select one solution:
+   1. Use dynamic library: Add `use_frameworks!` in Podfile.
+   2. Select Target Runner -> Build Settings -> Strip Style -> change from "All Symbols" to "Non-Global Symbols"
 
-## ❤️ Contributed
+## Contribution
 
 - If you **need help** or you'd like to **ask a general question**, open an issue.
 - If you **found a bug**, open an issue.
 - If you **have a feature request**, open an issue.
 - If you **want to contribute**, submit a pull request.
 
-## 👮🏻 License
+## License
 
-DartNative is available under the BSD 3-Clause License. See the LICENSE file for more info.
+DartNative is available under the BSD 3-Clause License. See the LICENSE file for more info.