From 36098189b35618fec8d1e8973476b91b3e71de85 Mon Sep 17 00:00:00 2001
From: Ivan Enderlin <ivan.enderlin@hoa-project.net>
Date: Wed, 17 Jul 2019 11:01:42 +0200
Subject: [PATCH] doc(runtime-c-api) Document and reorganize `exports.rs`.

This patch moves all structs at the beginning of the file, and
documents them.
---
 lib/runtime-c-api/src/export.rs | 63 ++++++++++++++++++++++-----------
 1 file changed, 43 insertions(+), 20 deletions(-)

diff --git a/lib/runtime-c-api/src/export.rs b/lib/runtime-c-api/src/export.rs
index cdb953e24..ecc35a0b5 100644
--- a/lib/runtime-c-api/src/export.rs
+++ b/lib/runtime-c-api/src/export.rs
@@ -16,26 +16,63 @@ use std::{ptr, slice};
 use wasmer_runtime::{Instance, Memory, Module, Value};
 use wasmer_runtime_core::{export::Export, module::ExportIndex};
 
+/// Intermediate representation of an `Export` instance that is
+/// exposed to C.
+pub(crate) struct NamedExport {
+    /// The export name.
+    pub(crate) name: String,
+
+    /// The export instance.
+    pub(crate) export: Export,
+
+    /// The instance that holds the export.
+    pub(crate) instance: *mut Instance,
+}
+
+/// Opaque pointer to `NamedExport`.
 #[repr(C)]
 #[derive(Clone)]
 pub struct wasmer_export_t;
 
-#[repr(C)]
-#[derive(Clone)]
-pub struct wasmer_exports_t;
-
+/// Opaque pointer to `wasmer_export_t`.
 #[repr(C)]
 #[derive(Clone)]
 pub struct wasmer_export_func_t;
 
+/// Intermediate representation of a vector of `NamedExport` that is
+/// exposed to C.
+pub(crate) struct NamedExports(pub Vec<NamedExport>);
+
+/// Opaque pointer to `NamedExports`.
+#[repr(C)]
+#[derive(Clone)]
+pub struct wasmer_exports_t;
+
+/// Intermediate representation of an export dsscriptor that is
+/// exposed to C.
+pub(crate) struct NamedExportDescriptor {
+    /// The export name.
+    name: String,
+
+    /// The export kind.
+    kind: wasmer_import_export_kind,
+}
+
+/// Opaque pointer to `NamedExportDescriptor`.
 #[repr(C)]
 #[derive(Clone)]
 pub struct wasmer_export_descriptor_t;
 
+/// Intermediate representation of a vector of `NamedExportDescriptor`
+/// that is exposed to C.
+pub struct NamedExportDescriptors(Vec<NamedExportDescriptor>);
+
+/// Opaque pointer to `NamedExportDescriptors`.
 #[repr(C)]
 #[derive(Clone)]
 pub struct wasmer_export_descriptors_t;
 
+/// Union of import/export value.
 #[repr(C)]
 #[derive(Clone, Copy)]
 pub union wasmer_import_export_value {
@@ -45,6 +82,7 @@ pub union wasmer_import_export_value {
     pub global: *const wasmer_global_t,
 }
 
+/// List of export/import kinds.
 #[allow(non_camel_case_types)]
 #[repr(u32)]
 #[derive(Clone)]
@@ -73,8 +111,6 @@ pub unsafe extern "C" fn wasmer_export_descriptors(
         Box::into_raw(named_export_descriptors) as *mut wasmer_export_descriptors_t;
 }
 
-pub struct NamedExportDescriptors(Vec<NamedExportDescriptor>);
-
 /// Frees the memory for the given export descriptors
 #[allow(clippy::cast_ptr_alignment)]
 #[no_mangle]
@@ -136,8 +172,6 @@ pub unsafe extern "C" fn wasmer_export_descriptor_kind(
     named_export_descriptor.kind.clone()
 }
 
-pub(crate) struct NamedExports(pub Vec<NamedExport>);
-
 /// Frees the memory for the given exports
 #[allow(clippy::cast_ptr_alignment)]
 #[no_mangle]
@@ -241,7 +275,7 @@ pub unsafe extern "C" fn wasmer_export_func_params(
     }
 }
 
-/// Sets the returns buffer to the parameter types of the given wasmer_export_func_t
+/// Sets the returns buffer to the parameter types of the given wasmer_xport_func_t
 ///
 /// Returns `wasmer_result_t::WASMER_OK` upon success.
 ///
@@ -428,14 +462,3 @@ impl From<(&std::string::String, &ExportIndex)> for NamedExportDescriptor {
         }
     }
 }
-
-pub(crate) struct NamedExport {
-    pub(crate) name: String,
-    pub(crate) export: Export,
-    pub(crate) instance: *mut Instance,
-}
-
-pub(crate) struct NamedExportDescriptor {
-    name: String,
-    kind: wasmer_import_export_kind,
-}