Merge rust-bitcoin/rust-secp256k1#437: Safety docs

dc1e377d4e Improve docs on rustsecp256k1_v0_4_1_context_create (Tobin C. Harding)
ad153d82f7 Add safety rustdoc headings (Tobin C. Harding)

Pull request description:

  Do some minor docs improvements.

  Done in an effort to clear _all_ clippy warnings from the codebase.

ACKs for top commit:
  sanket1729:
    ACK dc1e377d4e
  apoelstra:
    ACK dc1e377d4e

Tree-SHA512: 9b7e3ff05a6ea05bde5df49bbfcc6eb2c7097b4d9b600dedeb8fef4e3cbdd56a357fd0846ca51cb32f0957bca1335ff3b4b0d771046481ab95447af99d6a2d9c

secp256k1-sys/src/lib.rs

@@ -109,6 +109,8 @@ impl_raw_debug!(PublicKey);
 impl PublicKey {
     /// Creates an "uninitialized" FFI public key which is zeroed out
     ///
+    /// # Safety
+    ///
     /// If you pass this to any FFI functions, except as an out-pointer,
     /// the result is likely to be an assertation failure and process
     /// termination.
@@ -118,6 +120,8 @@ impl PublicKey {
 
     /// Create a new public key usable for the FFI interface from raw bytes
     ///
+    /// # Safety
+    ///
     /// Does not check the validity of the underlying representation. If it is
     /// invalid the result may be assertation failures (and process aborts) from
     /// the underlying library. You should not use this method except with data
@@ -145,6 +149,8 @@ impl_raw_debug!(Signature);
 impl Signature {
     /// Creates an "uninitialized" FFI signature which is zeroed out
     ///
+    /// # Safety
+    ///
     /// If you pass this to any FFI functions, except as an out-pointer,
     /// the result is likely to be an assertation failure and process
     /// termination.
@@ -154,6 +160,8 @@ impl Signature {
 
     /// Create a new signature usable for the FFI interface from raw bytes
     ///
+    /// # Safety
+    ///
     /// Does not check the validity of the underlying representation. If it is
     /// invalid the result may be assertation failures (and process aborts) from
     /// the underlying library. You should not use this method except with data
@@ -180,6 +188,8 @@ impl_raw_debug!(XOnlyPublicKey);
 impl XOnlyPublicKey {
     /// Creates an "uninitialized" FFI x-only public key which is zeroed out
     ///
+    /// # Safety
+    ///
     /// If you pass this to any FFI functions, except as an out-pointer,
     /// the result is likely to be an assertation failure and process
     /// termination.
@@ -189,6 +199,8 @@ impl XOnlyPublicKey {
 
     /// Create a new x-only public key usable for the FFI interface from raw bytes
     ///
+    /// # Safety
+    ///
     /// Does not check the validity of the underlying representation. If it is
     /// invalid the result may be assertation failures (and process aborts) from
     /// the underlying library. You should not use this method except with data
@@ -215,6 +227,8 @@ impl_raw_debug!(KeyPair);
 impl KeyPair {
     /// Creates an "uninitialized" FFI keypair which is zeroed out
     ///
+    /// # Safety
+    ///
     /// If you pass this to any FFI functions, except as an out-pointer,
     /// the result is likely to be an assertation failure and process
     /// termination.
@@ -224,6 +238,8 @@ impl KeyPair {
 
     /// Create a new keypair usable for the FFI interface from raw bytes
     ///
+    /// # Safety
+    ///
     /// Does not check the validity of the underlying representation. If it is
     /// invalid the result may be assertation failures (and process aborts) from
     /// the underlying library. You should not use this method except with data
@@ -519,12 +535,14 @@ extern "C" {
 
 /// A reimplementation of the C function `secp256k1_context_create` in rust.
 ///
-/// This function allocates memory, the pointer should be deallocated using `secp256k1_context_destroy`
+/// This function allocates memory, the pointer should be deallocated using
-/// A failure to do so will result in a memory leak.
+/// `secp256k1_context_destroy`. Failure to do so will result in a memory leak.
 ///
-/// This will create a secp256k1 raw context.
+/// Input `flags` control which parts of the context to initialize.
-// Returns: a newly created context object.
+///
-//  In:      flags: which parts of the context to initialize.
+/// # Returns
+///
+/// The newly created secp256k1 raw context.
 #[no_mangle]
 #[cfg(all(feature = "std", not(rust_secp_no_symbol_renaming)))]
 #[cfg_attr(docsrs, doc(cfg(all(feature = "std", not(rust_secp_no_symbol_renaming)))))]