Merge remote-tracking branch 'origin/master' into feature/unified-exceptions

Author: losfair

lib/runtime-c-api/src/error.rs

@@ -22,16 +22,12 @@ pub(crate) fn take_last_error() -> Option<Box<dyn Error>> {
     LAST_ERROR.with(|prev| prev.borrow_mut().take())
 }
 
-/// Gets the length in bytes of the last error.
+/// Gets the length in bytes of the last error if any.
+///
 /// This can be used to dynamically allocate a buffer with the correct number of
 /// bytes needed to store a message.
 ///
-/// # Example
-///
-/// ```c
-/// int error_len = wasmer_last_error_length();
-/// char *error_str = malloc(error_len);
-/// ```
+/// See `wasmer_last_error_message()` to get a full example.
 #[no_mangle]
 pub extern "C" fn wasmer_last_error_length() -> c_int {
     LAST_ERROR.with(|prev| match *prev.borrow() {
@@ -40,19 +36,33 @@ pub extern "C" fn wasmer_last_error_length() -> c_int {
     })
 }
 
-/// Stores the last error message into the provided buffer up to the given `length`.
-/// The `length` parameter must be large enough to store the last error message.
+/// Gets the last error message if any into the provided buffer
+/// `buffer` up to the given `length`.
 ///
-/// Returns the length of the string in bytes.
-/// Returns `-1` if an error occurs.
+/// The `length` parameter must be large enough to store the last
+/// error message. Ideally, the value should come from
+/// `wasmer_last_error_length()`.
 ///
-/// # Example
+/// The function returns the length of the string in bytes, `-1` if an
+/// error occurs. Potential errors are:
+///
+///  * The buffer is a null pointer,
+///  * The buffer is too smal to hold the error message.
+///
+/// Note: The error message always has a trailing null character.
+///
+/// Example:
 ///
 /// ```c
-/// int error_len = wasmer_last_error_length();
-/// char *error_str = malloc(error_len);
-/// wasmer_last_error_message(error_str, error_len);
-/// printf("Error str: `%s`\n", error_str);
+/// int error_length = wasmer_last_error_length();
+///
+/// if (error_length > 0) {
+///     char *error_message = malloc(error_length);
+///     wasmer_last_error_message(error_message, error_length);
+///     printf("Error message: `%s`\n", error_message);
+/// } else {
+///     printf("No error message\n");
+/// }
 /// ```
 #[no_mangle]
 pub unsafe extern "C" fn wasmer_last_error_message(buffer: *mut c_char, length: c_int) -> c_int {

lib/runtime-c-api/src/export.rs

@@ -43,7 +43,11 @@ pub struct wasmer_export_func_t;
 /// exposed to C.
 pub(crate) struct NamedExports(pub Vec<NamedExport>);
 
-/// Opaque pointer to `NamedExports`.
+/// Opaque pointer to the opaque structure `crate::NamedExports`,
+/// which is a wrapper around a vector of the opaque structure
+/// `crate::NamedExport`.
+///
+/// Check the `wasmer_instance_exports()` function to learn more.
 #[repr(C)]
 #[derive(Clone)]
 pub struct wasmer_exports_t;
@@ -91,9 +95,16 @@ pub union wasmer_import_export_value {
 // ================
 // Do not modify these values without updating the `TryFrom` implementation below
 pub enum wasmer_import_export_kind {
+    /// The export/import is a function.
     WASM_FUNCTION = 0,
+
+    /// The export/import is a global.
     WASM_GLOBAL = 1,
+
+    /// The export/import is a memory.
     WASM_MEMORY = 2,
+
+    /// The export/import is a table.
     WASM_TABLE = 3,
 }
 
@@ -201,7 +212,23 @@ pub unsafe extern "C" fn wasmer_export_descriptor_kind(
     named_export_descriptor.kind.clone()
 }
 
-/// Frees the memory for the given exports
+/// Frees the memory for the given exports.
+///
+/// Check the `wasmer_instance_exports()` function to get a complete
+/// example.
+///
+/// If `exports` is a null pointer, this function does nothing.
+///
+/// Example:
+///
+/// ```c
+/// // Get some exports.
+/// wasmer_exports_t *exports = NULL;
+/// wasmer_instance_exports(instance, &exports);
+///
+/// // Destroy the exports.
+/// wasmer_exports_destroy(exports);
+/// ```
 #[allow(clippy::cast_ptr_alignment)]
 #[no_mangle]
 pub extern "C" fn wasmer_exports_destroy(exports: *mut wasmer_exports_t) {