From 39a10e9fc973d7495b7dd03a163a4e1be23b4286 Mon Sep 17 00:00:00 2001
From: Sergey Pepyakin <s.pepyakin@gmail.com>
Date: Fri, 26 Jan 2018 18:21:12 +0300
Subject: [PATCH] Document FuncInstance::{alloc_host, signature}

---
 src/func.rs | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/src/func.rs b/src/func.rs
index 46aebd1..bd1649a 100644
--- a/src/func.rs
+++ b/src/func.rs
@@ -77,6 +77,15 @@ impl fmt::Debug for FuncInstance {
 }
 
 impl FuncInstance {
+
+	/// Allocate a function instance for a host function.
+	///
+	/// When this function instance will be called by the wasm code,
+	/// the instance of [`Externals`] will be invoked by calling `invoke_index`
+	/// with specified `host_func_index` here.
+	/// This call will be made with the `signature` provided here.
+	///
+	/// [`Externals`]: trait.Externals.html
 	pub fn alloc_host(signature: Signature, host_func_index: usize) -> FuncRef {
 		let func = FuncInstanceInternal::Host {
 			signature,
@@ -85,6 +94,18 @@ impl FuncInstance {
 		FuncRef(Rc::new(FuncInstance(func)))
 	}
 
+	/// Returns [signature] of this function instance.
+	///
+	/// This function instance can only be called with matching signatures.
+	///
+	/// [signature]: struct.Signature.html
+	pub fn signature(&self) -> &Signature {
+		match *self.as_internal() {
+			FuncInstanceInternal::Internal { ref signature, .. } => signature,
+			FuncInstanceInternal::Host { ref signature, .. } => signature,
+		}
+	}
+
 	pub(crate) fn as_internal(&self) -> &FuncInstanceInternal {
 		&self.0
 	}
@@ -102,13 +123,6 @@ impl FuncInstance {
 		FuncRef(Rc::new(FuncInstance(func)))
 	}
 
-	pub fn signature(&self) -> &Signature {
-		match *self.as_internal() {
-			FuncInstanceInternal::Internal { ref signature, .. } => signature,
-			FuncInstanceInternal::Host { ref signature, .. } => signature,
-		}
-	}
-
 	pub(crate) fn body(&self) -> Option<Rc<FuncBody>> {
 		match *self.as_internal() {
 			FuncInstanceInternal::Internal { ref body, .. } => Some(Rc::clone(body)),