Add docs for AlignType and preallocation, and update preallocate tests

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 [AlignType](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 [AlignType](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 [AlignType](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()

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 [AlignType](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>());
@@ -716,7 +719,7 @@ mod tests {
         let ctx_sign = unsafe { ffi::secp256k1_context_create(SignOnlyPreallocated::FLAGS) };
         let ctx_vrfy = unsafe { ffi::secp256k1_context_create(VerifyOnlyPreallocated::FLAGS) };
 
-        let buf: *mut [u8] = &mut [0u8;0] as _;
+        let buf: *mut [AlignType] = &mut [0 as AlignType;0] as _;
         let full: Secp256k1<AllPreallocated> = Secp256k1{ctx: ctx_full, phantom: PhantomData, buf};
         let sign: Secp256k1<SignOnlyPreallocated> = Secp256k1{ctx: ctx_sign, phantom: PhantomData, buf};
         let vrfy: Secp256k1<VerifyOnlyPreallocated> = Secp256k1{ctx: ctx_vrfy, phantom: PhantomData, buf};
@@ -740,10 +743,10 @@ mod tests {
 
     #[test]
     fn test_preallocation() {
-        let mut buf_ful = vec![0u8; Secp256k1::preallocate_size()];
-        let mut buf_sign = vec![0u8; Secp256k1::preallocate_signing_size()];
-        let mut buf_vfy = vec![0u8; Secp256k1::preallocate_verification_size()];
-//
+        let mut buf_ful = vec![0; Secp256k1::preallocate_size()];
+        let mut buf_sign = vec![0; Secp256k1::preallocate_signing_size()];
+        let mut buf_vfy = vec![0; Secp256k1::preallocate_verification_size()];
+
         let full = Secp256k1::preallocated_new(&mut buf_ful).unwrap();
         let sign = Secp256k1::preallocated_signing_only(&mut buf_sign).unwrap();
         let vrfy = Secp256k1::preallocated_verification_only(&mut buf_vfy).unwrap();