From 96cd57a6958e00ddc34773ed603b9caed27e2c77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bastian=20K=C3=B6cher?= <bkchr@users.noreply.github.com>
Date: Sun, 19 Jan 2020 01:51:03 +0100
Subject: [PATCH] Make use of `cfg(doc)` in `sp-runtime-interface` (#4673)
By using `cfg(doc)`, we can generate docs for modules which are only
available from `no_std`. This drastically improves the documentation for
the developers.
---
.../src/runtime_interface/bare_function_interface.rs | 4 ++--
substrate/primitives/runtime-interface/src/host.rs | 3 +++
substrate/primitives/runtime-interface/src/lib.rs | 10 +++++-----
substrate/primitives/runtime-interface/src/wasm.rs | 3 ++-
4 files changed, 12 insertions(+), 8 deletions(-)
diff --git a/substrate/primitives/runtime-interface/proc-macro/src/runtime_interface/bare_function_interface.rs b/substrate/primitives/runtime-interface/proc-macro/src/runtime_interface/bare_function_interface.rs
index 55b5eb3a4d6..bdddc5eba70 100644
--- a/substrate/primitives/runtime-interface/proc-macro/src/runtime_interface/bare_function_interface.rs
+++ b/substrate/primitives/runtime-interface/proc-macro/src/runtime_interface/bare_function_interface.rs
@@ -21,10 +21,10 @@
//! functions will prepare the parameters for the FFI boundary, call the external host function
//! exported into wasm and convert back the result.
//!
-//! [`generate`](bare_function_interface::generate) is the entry point for generating for each
+//! [`generate`] is the entry point for generating for each
//! trait method one bare function.
//!
-//! [`function_for_method`](bare_function_interface::function_for_method) generates the bare
+//! [`function_for_method`] generates the bare
//! function per trait method. Each bare function contains both implementations. The implementations
//! are feature-gated, so that one is compiled for the native and the other for the wasm side.
diff --git a/substrate/primitives/runtime-interface/src/host.rs b/substrate/primitives/runtime-interface/src/host.rs
index 2fc272165f3..cf03e6623af 100644
--- a/substrate/primitives/runtime-interface/src/host.rs
+++ b/substrate/primitives/runtime-interface/src/host.rs
@@ -49,6 +49,9 @@ pub trait IntoPreallocatedFFIValue: RIType {
}
/// Something that can be created from a ffi value.
+/// Implementations are safe to assume that the `arg` given to `from_ffi_value`
+/// is only generated by the corresponding [`wasm::IntoFFIValue`](crate::wasm::IntoFFIValue)
+/// implementation.
pub trait FromFFIValue: RIType {
/// As `Self` can be an unsized type, it needs to be represented by a sized type at the host.
/// This `SelfInstance` is the sized type.
diff --git a/substrate/primitives/runtime-interface/src/lib.rs b/substrate/primitives/runtime-interface/src/lib.rs
index 189126440b9..30d74ad2db3 100644
--- a/substrate/primitives/runtime-interface/src/lib.rs
+++ b/substrate/primitives/runtime-interface/src/lib.rs
@@ -25,10 +25,10 @@
//! # Using a type in a runtime interface
//!
//! Any type that should be used in a runtime interface as argument or return value needs to
-//! implement [`RIType`]. The associated type `FFIType` is the type that is used in the FFI
-//! function to represent the actual type. For example `[T]` is represented by an `u64`. The slice
-//! pointer and the length will be mapped to an `u64` value. For more information, see the
-//! implementation of [`RIType`] for `T`. The FFI function definition is used when calling from
+//! implement [`RIType`]. The associated type [`FFIType`](RIType::FFIType) is the type that is used
+//! in the FFI function to represent the actual type. For example `[T]` is represented by an `u64`.
+//! The slice pointer and the length will be mapped to an `u64` value. For more information see
+//! this [table](#ffi-type-and-conversion). The FFI function definition is used when calling from
//! the wasm runtime into the node.
//!
//! Traits are used to convert from a type to the corresponding [`RIType::FFIType`].
@@ -265,7 +265,7 @@ pub use codec;
pub(crate) mod impls;
#[cfg(feature = "std")]
pub mod host;
-#[cfg(not(feature = "std"))]
+#[cfg(any(not(feature = "std"), doc))]
pub mod wasm;
pub mod pass_by;
diff --git a/substrate/primitives/runtime-interface/src/wasm.rs b/substrate/primitives/runtime-interface/src/wasm.rs
index 476dfb8a4ce..a0801c2bfb5 100644
--- a/substrate/primitives/runtime-interface/src/wasm.rs
+++ b/substrate/primitives/runtime-interface/src/wasm.rs
@@ -26,7 +26,8 @@ use sp_std::cell::Cell;
///
/// It is unsafe behavior to call `Something::into_ffi_value().get()` and take this as input for
/// `from_ffi_value`. Implementations are safe to assume that the `arg` given to `from_ffi_value`
-/// is only generated by the corresponding `host::IntoFFIValue` implementation.
+/// is only generated by the corresponding [`host::IntoFFIValue`](crate::host::IntoFFIValue)
+/// implementation.
pub trait FromFFIValue: Sized + RIType {
/// Create `Self` from the given ffi value.
fn from_ffi_value(arg: Self::FFIType) -> Self;
--
GitLab