refactor: refactor ffi design document

assets/c-friendly-ffi-design/c-cpp-side.md

@@ -0,0 +1 @@
+# C/C++ Side

assets/c-friendly-ffi-design/c-cpp-side/c-header.md

@@ -1,4 +1,4 @@
-# C/C++ Headers
+# C Header
 
 Under this section we discuss how to write the C/C++ header files that accompany the
 Rust FFI library. The Rust-side counterpart of each topic is covered in

assets/c-friendly-ffi-design/c-cpp-side/cpp-header.md

@@ -0,0 +1,3 @@
+# C++ Header
+
+

assets/c-friendly-ffi-design/c-cpp-side/example.md

@@ -0,0 +1,15 @@
+# C/C++ Headers Example
+
+
+
+## C Header Example
+
+```c
+
+```
+
+## C++ Header Example
+
+```c++
+
+```

assets/c-friendly-ffi-design/c-cpp-side/misc.md

@@ -0,0 +1 @@
+# Miscellaneous Stuff

assets/c-friendly-ffi-design/index.md

@@ -8,6 +8,14 @@ to write the accompanying C/C++ header files.
 
 ## Contents
 
-- [FFI Function Signatures](ffi-function-signatures.md)
+* [Rust Side](rust-side.md)
-- [Allowed Data Types](allowed-data-types.md)
+    - [FFI Function Signature](rust-side/func-signature.md)
-- [C/C++ Headers](c-cpp-headers.md)
+    - [Allowed Data Types](rust-side/data-types.md)
+    - [FFI Example](rust-side/example.md)
+    - [Miscellaneous Stuff](rust-side/misc.md)
+* [C/C++ Side](c-cpp-side.md)
+    - [C Header](c-cpp-side/c-header.md)
+    - [C++ Header](c-cpp-side/cpp-header.md)
+    - [C/C++ Headers Example](c-cpp-side/example.md)
+    - [Miscellaneous Stuff](c-cpp-side/misc.md)
+* [Pack Distribution](packer.md)

assets/c-friendly-ffi-design/packer.md

@@ -0,0 +1,2 @@
+# Pack Distribution
+

assets/c-friendly-ffi-design/rust-side.md

@@ -0,0 +1,4 @@
+# Rust Side
+
+
+

assets/c-friendly-ffi-design/rust-side/example.md

@@ -0,0 +1,15 @@
+# FFI Example
+
+
+
+## Rust Core Crate
+
+```rust
+
+```
+
+## Rust FFI Binding Crate
+
+```rust
+
+```

assets/c-friendly-ffi-design/rust-side/func-signature.md

@@ -1,15 +1,15 @@
-# FFI Function Signatures
+# FFI Function Signature
 
 Under this section we discuss the signature requirements of the exported FFI
 functions.
 
-## C-style Name Export
+## The Way of Exporting Function
 
 FFI functions must be exported under C names, that is, they must not go through the
 C++ name mangling mechanism.
 
-In Rust, you need to decorate the function with the `#[unsafe(no_mangle)]` attribute
+This requirement means that, in Rust, you need to decorate the function with the 
-together with `extern "C"`, for example:
+`#[unsafe(no_mangle)]` attribute together with `extern "C"`, for example:
 
 ```rust
 #[unsafe(no_mangle)]
@@ -20,7 +20,7 @@ pub extern "C" fn WFStartup() -> CError {
 // More FFI functions omitted...
 ```
 
-## Export Name Style
+## Function Name Styles
 
 In this subsection, we discuss the naming style of exported functions.
 
@@ -93,10 +93,11 @@ The following examples show some legal and illegal POSIX style function names:
 | `wf_GetMessage` | Illegal | `<FUNC>`, which is `GetMessage`, is not snake_case. |
 | `wf_Icon_get_message` | Illegal | `<STRUCT>`, which is `Icon`, is not snake_case. |
 
-## Parameters and Return Value
+## Function Signature Rules
 
-Under this section we discuss the parameters and return value of the exported
+Under this subsection we discuss the parameters and return value of the exported
-functions. A standard FFI function looks like the following on the Rust side:
+functions. A standard FFI function following this design looks like the following
+on the Rust side:
 
 ```rust
 #[unsafe(no_mangle)]
@@ -160,10 +161,9 @@ absolute, unambiguous success. Every other value's meaning is decided by the
 consuming project: it may denote a failure, or, like some Win32 functions, a
 partial success.
 
-#### Migrating from a bool Return Value
+> [!TIP]
-
+> Projects that previously returned a plain `bool` can adopt the error-code scheme
-Projects that previously returned a plain `bool` can adopt the error-code scheme
+> with minimal change: define exactly one non-success code, for example
-with minimal change: define exactly one non-success code, for example
+> `const CERROR_FAIL: CError = 1;`, and map every error type to it. The result is
-`const CERROR_FAIL: CError = 1;`, and map every error type to it. The result is
+> equivalent to a `bool`: `CERROR_OK` for success and `CERROR_FAIL` for any failure,
-equivalent to a `bool`: `CERROR_OK` for success and `CERROR_FAIL` for any failure,
+> while leaving room to introduce finer-grained codes later.
-while leaving room to introduce finer-grained codes later.

assets/c-friendly-ffi-design/rust-side/misc.md

@@ -0,0 +1 @@
+# Miscellaneous Stuff