From aece3f37080e3a2e042ee29249c17adf90f4d549 Mon Sep 17 00:00:00 2001
From: Simon Asika <asika32764@gmail.com>
Date: Tue, 4 Jun 2024 17:09:38 +0800
Subject: [PATCH] promise docs wip

---
 .vitepress/theme/CustomLayout.vue          |  6 +-
 documentation/components/di/attributes.md  |  8 +++
 documentation/components/di/basic-usage.md | 15 +++++
 documentation/components/promise/index.md  | 67 ++++++++++++++++++++--
 4 files changed, 89 insertions(+), 7 deletions(-)

diff --git a/.vitepress/theme/CustomLayout.vue b/.vitepress/theme/CustomLayout.vue
index f94ca392..bfc37614 100644
--- a/.vitepress/theme/CustomLayout.vue
+++ b/.vitepress/theme/CustomLayout.vue
@@ -4,6 +4,7 @@ import DefaultTheme from 'vitepress/theme';
 import { computed } from 'vue';
 import { flatComponents } from '../data/components';
 import { componentRoutePrefix } from '../store/routing-store';
+import icon from '../../public/images/logo-icon.png';
 // import { register } from 'swiper/element/bundle';
 // register();
 
@@ -44,7 +45,10 @@ const isComponent = computed(() => !!page.value.frontmatter.component);
 
   <template #doc-before>
     <div v-if="isComponent" class="c-card" style="margin-bottom: 2rem; padding: 1.5rem; ">
-      <div style="display: flex; gap: .5rem; margin-bottom: .5rem;">
+      <div style="display: flex; gap: .5rem; margin-bottom: .5rem; align-items: center">
+        <img :src="icon"
+            style="height: 30px"
+            alt="Windwalker">
         <a :href="`/${componentRoutePrefix}/${component.alias}/`">
           <h2 style="font-size: 1.5rem;">{{ component.title }}</h2>
         </a>
diff --git a/documentation/components/di/attributes.md b/documentation/components/di/attributes.md
index 676867ca..348230d5 100644
--- a/documentation/components/di/attributes.md
+++ b/documentation/components/di/attributes.md
@@ -230,3 +230,11 @@ $resolver->registerAttribute(MyAttribute::class, AttributeType::CLASSES);
 ```
 
 See [Attributes Component](../attributes/)
+
+## Ignore Attributes
+
+Use `Container::IGNORE_ATTRIBUTES` to make all attributes don't work:
+
+```php
+$container->newInstance(Foo::class, options: Container::IGNORE_ATTRIBUTES);
+```
diff --git a/documentation/components/di/basic-usage.md b/documentation/components/di/basic-usage.md
index bcca7463..2b13e934 100644
--- a/documentation/components/di/basic-usage.md
+++ b/documentation/components/di/basic-usage.md
@@ -85,6 +85,8 @@ $container->set('input', $otherInput);
 
 ## Alias
 
+Set an alias to service ID that you can use alias to get service:
+
 ```php
 $container->share('system.application', $app)
     ->alias('app', 'system.application');
@@ -93,6 +95,17 @@ $container->share('system.application', $app)
 $app = $container->get('app');
 ```
 
+Set alias by class name:
+
+```php
+$container->prepareSharedObject(SystemApp::class)
+    ->alias(MainApp::class, SystemApp::class);
+
+// Same as `SystemApp::class`
+$app = $container->get(MainApp::class);
+```
+
+
 ## Creating Objects
 
 ### New Instance
@@ -368,3 +381,5 @@ $result = $container->call($closure, [
 // Use Autowire
 $result = $container->call($closure, [], Container::AUTO_WIRE);
 ```
+
+
diff --git a/documentation/components/promise/index.md b/documentation/components/promise/index.md
index 624b366b..b065ae45 100644
--- a/documentation/components/promise/index.md
+++ b/documentation/components/promise/index.md
@@ -1,9 +1,7 @@
 ---
 layout: doc
 title: Introduction
-part: Components
-chapter: Promise
-menu: components/promise
+component: promise
 ---
 
 # Introduction
@@ -20,12 +18,69 @@ composer require windwalker/promise ^4.0
 
 ## Use in Windwalker
 
-...
+Use any component which is support async calling, the promise will be return value:
+
+```php
+// Http Client
+$http = new \Windwalker\Http\HttpClient();
+
+$http->postAsync(...)->then(fn () => ...);
+
+// File Async operation
+$file = \Windwalker\fs('/path/to/file');
+
+$file->deleteAsync()->then(fn () => ...);
+```
 
 ## Use as Standalone Component
 
-...
+```php
+use Windwalker\Promise\Promise;
+
+$promise = new Promise(function ($resolve, $reject) {
+    $resolve(...);
+});
+
+$promise->wait();
+```
 
 ## Getting Started
 
-...
+### How Promise Works in Pure PHP
+
+PHP is synchronous, if we run PHP in Apache module, FPM or CGI, there won't be any asynchronous process.
+
+Windwalker Promise makes a queue to store all your async tasks, it will wait until PHP process end (For example, when the process shutdown or running to the end), and run the all tasks.
+
+For example, below codes trying to send mail asynchronous, when `runAndSendMail()` completed, the promise then task will push to a global task queue and not running instantly, this task will be executed after whole process end, so user won't experience a block when system trying to send mail. 
+
+```php
+use Windwalker\Promise\Promise;
+
+function runAndSendMail() {
+    // Do something
+    
+    // Start to send mail
+    return Promise::resolved()
+        ->then(function () {
+            // This will run after process end
+            Mailer::send(...);
+        });
+}
+
+runAndSendMail()->then(...);
+```
+
+### Force Wait
+
+If you want to force all async tasks run, you may use `wait()` to make PHP wait and block:
+
+```php
+$promise = runAndSendMail();
+
+// This will run through all tasks and block
+$promise->wait();
+
+// After all tasks executed, process will resume
+```
+