doc: update ffi design

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

@@ -5,25 +5,6 @@ Rust FFI library. The Rust-side counterpart of each topic is covered in
 [FFI Function Signatures](ffi-function-signatures.md) and
 [Allowed Data Types](allowed-data-types.md).
 
-## Include Guard
-
-When writing the include guard of a C header file, we require using both the modern `#pragma once` approach and the traditional approach based on the `#ifndef`, `#define` and `#endif` preprocessing directives. The file should be written like this:
-
-```c
-#pragma once
-#ifndef SOME_HEADER_H_
-#define SOME_HEADER_H_
-
-// The actual content of the header file...
-
-#endif  // SOME_HEADER_H_
-```
-
-The `SOME_HEADER` prefix is usually related to the name of the header file. It must consist of all uppercase characters, but underscores are allowed. The `_H_` suffix is fixed and cannot be changed; this suffix style originates from the Linux kernel.
-
-For example, when the header file is named `wfassoc.h`, the macro name would be `WFASSOC_H_`.
-However, if the name of the header file is too simple and may collide with other header files, it would be better to prepend something to the prefix to remove this ambiguity. For example, for a project called MyRust with a header file named `utils.h`, a good macro name would be `MY_RUST_UTILS_H_`.
-
 ## Function Declaration Style
 
 FFI functions must be exported under C names, that is, they must not go through the

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

@@ -1,6 +1,2 @@
 # C++ Header
 
-## Include Guard
-
-The include guard requirement in the C++ header files is identical to the one in the C header files.
-

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

@@ -78,7 +78,7 @@ An example is shown below:
  * @param[out] out_c Example output parameter.
  * @return Example return value.
  */
-int FlFooBar(OMRF_IN(int) in_a, OMRF_IN(int) in_b, OMRF_OUT(int) out_c);
+int FlFooBar(OMRF_IN_PARAM_TY(int) in_a, OMRF_IN_PARAM_TY(int) in_b, OMRF_OUT_PARAM_TY(int) out_c);
 ```
 
 ### Object Docstring
@@ -352,7 +352,7 @@ When the following situations occur, additional requirements apply to the corres
 
 When a parameter carries a pointer, the `@param` annotation of that parameter must state whether the pointer could be NULL (for output) or whether passing NULL is allowed (for input).
 
-Note that the pointer mentioned here refers to the case where the type decorated by `OMRF_IN` or `OMRF_OUT` is itself a pointer type. Since every output parameter is passed by pointer, the pointer mentioned above does not refer to that pointer created by the output decoration.
+Note that the pointer mentioned here refers to the case where the type decorated by `OMRF_IN_PARAM_TY` or `OMRF_OUT_PARAM_TY` is itself a pointer type. Since every output parameter is passed by pointer, the pointer mentioned above does not refer to that pointer created by the output decoration.
 
 ### String Lifetime
 

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

@@ -1 +1,47 @@
 # Miscellaneous Stuff
+
+## Include Guard
+
+When writing the include guard of a C/C++ header file, we require using both the modern `#pragma once` approach and the traditional approach based on the `#ifndef`, `#define` and `#endif` preprocessing directives. The file should be written like this:
+
+```c
+#pragma once
+#ifndef SOME_HEADER_H_
+#define SOME_HEADER_H_
+
+// The actual content of the header file...
+
+#endif  // SOME_HEADER_H_
+```
+
+The `SOME_HEADER` prefix is usually related to the name of the header file. It must consist of all uppercase characters, but underscores are allowed. The `_H_` suffix is fixed and cannot be changed; this suffix style originates from the Linux kernel.
+
+For example, when the header file is named `wfassoc.h`, the macro name would be `WFASSOC_H_`.
+However, if the name of the header file is too simple and may collide with other header files, it would be better to prepend something to the prefix to remove this ambiguity. For example, for a project called MyRust with a header file named `utils.h`, a good macro name would be `MY_RUST_UTILS_H_`.
+
+## Block Closing Annotations
+
+When we use preprocessor directives such as `#if` or `#ifdef` to conditionally enable or disable some code, we require you to annotate the condition after its matching `#else` and `#endif`, as shown below:
+
+```c
+#ifdef __cplusplus
+// Contents omitted...
+#else // __cplusplus
+// Contents omitted...
+#endif // __cplusplus
+```
+
+Besides the preprocessor directives, you also need to write similar closing annotations for `namespace` (C++ only) and `extern "C"` blocks (C++ only), for example:
+
+```c++
+extern "C" {
+    // Contents omitted...
+} // extern "C"
+
+namespace foobar {
+    // Contents omitted...
+} // namespace foobar
+```
+
+Note that the spaces around the `//` comment markers in the examples are required.
+