From 8477d9fc2796792700c8969756e7aef93c51fe16 Mon Sep 17 00:00:00 2001
From: Elichai Turkel <elichai.turkel@gmail.com>
Date: Thu, 8 Aug 2019 13:54:03 -0400
Subject: [PATCH] Add docs for AlignType and preallocation, and update
 preallocate tests

---
 src/context.rs | 45 ++++++++++++++++++++++++++++++++++++++++++---
 src/lib.rs     |  3 +++
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/src/context.rs b/src/context.rs
index fa4f4ccca..b1462e648 100644
--- a/src/context.rs
+++ b/src/context.rs
@@ -7,9 +7,15 @@ use Secp256k1;
 #[cfg(feature = "std")]
 pub use self::std_only::*;
 
+/// A type that represents the type with the biggest alignment we can get in rust.
+/// Trying to match what `malloc` does in C, this should be aligned enough to contain pointers too.
+/// This type can have different size/alignment depending on the architecture.
 #[cfg(any(target_pointer_width = "32", target_pointer_width = "16", target_pointer_width = "8"))]
 pub type AlignType = u64;
 
+/// A type that represents the type with the biggest alignment we can get in rust.
+/// Trying to match what `malloc` does in C, this should be aligned enough to contain pointers too.
+/// This type can have different size/alignment depending on the architecture.
 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "16", target_pointer_width = "8")))]
 pub type AlignType = usize;
 
@@ -202,7 +208,18 @@ impl<'buf> Secp256k1<AllPreallocated<'buf>> {
     pub fn preallocated_new(buf: &'buf mut [AlignType]) -> Result<Secp256k1<AllPreallocated<'buf>>, Error> {
         Secp256k1::preallocated_gen_new(buf)
     }
-    /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for a context
+    /// Returns the required memory for a preallocated context buffer in a generic manner(sign/verify/all)
+    /// 
+    /// Notice that the memory returned is in [AlignedType](type.AlignType.html)
+    ///
+    /// ## Examples
+    /// ```rust
+    /// # use secp256k1::*;
+    /// let buf_size = Secp256k1::preallocate_size();
+    /// let mut buf = vec![0; buf_size];
+    /// let secp = Secp256k1::preallocated_new(&mut buf).unwrap();
+    ///
+    /// ```
     pub fn preallocate_size() -> usize {
         Self::preallocate_size_gen()
     }
@@ -214,7 +231,18 @@ impl<'buf> Secp256k1<SignOnlyPreallocated<'buf>> {
         Secp256k1::preallocated_gen_new(buf)
     }
 
-    /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context
+    /// Returns the required memory for a preallocated context buffer in a generic manner(sign/verify/all)
+    /// 
+    /// Notice that the memory returned is in [AlignedType](type.AlignType.html)
+    ///
+    /// ## Examples
+    /// ```rust
+    /// # use secp256k1::*;
+    /// let buf_size = Secp256k1::preallocate_signing_size();
+    /// let mut buf = vec![0; buf_size];
+    /// let secp = Secp256k1::preallocated_signing_only(&mut buf).unwrap();
+    ///
+    /// ```
     #[inline]
     pub fn preallocate_signing_size() -> usize {
         Self::preallocate_size_gen()
@@ -227,7 +255,18 @@ impl<'buf> Secp256k1<VerifyOnlyPreallocated<'buf>> {
         Secp256k1::preallocated_gen_new(buf)
     }
 
-    /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context
+    /// Returns the required memory for a preallocated context buffer in a generic manner(sign/verify/all)
+    /// 
+    /// Notice that the memory returned is in [AlignedType](type.AlignType.html)
+    ///
+    /// ## Examples
+    /// ```rust
+    /// # use secp256k1::*;
+    /// let buf_size = Secp256k1::preallocate_verification_size();
+    /// let mut buf = vec![0; buf_size];
+    /// let secp = Secp256k1::preallocated_verification_only(&mut buf).unwrap();
+    ///
+    /// ```
     #[inline]
     pub fn preallocate_verification_size() -> usize {
         Self::preallocate_size_gen()
diff --git a/src/lib.rs b/src/lib.rs
index 1f7835828..18f5513fa 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -573,6 +573,9 @@ impl<C: Context> Secp256k1<C> {
     }
 
     /// Returns the required memory for a preallocated context buffer in a generic manner(sign/verify/all)
+    ///
+    /// Notice that the memory returned is in [AlignedType](type.AlignType.html)
+    ///
     pub fn preallocate_size_gen() -> usize {
         assert!(mem::align_of::<AlignType>() >= mem::align_of::<u8>());
         assert!(mem::align_of::<AlignType>() >= mem::align_of::<usize>());