Merge #861: Fix missing docs

1e06074 Fix missing docs (Tobin C. Harding)

Pull request description:

  Process fail, we cut the docs off on these two functions.
  
  Fix the docs using text taken directly from Poelstra's post on the issue.
  
  Close #847


ACKs for top commit:
  apoelstra:
    ACK 1e06074; successfully ran local tests except for the flakey one


Tree-SHA512: b8de71a73924e68022712432a2c3921f93a983e8f80496a6fa334fb5816b23b4bd6b6cdea551db2bb0062f60e305988c8c7d9b0b976a0392cf8234e63631b6bf

Author: apoelstra

src/context/internal_std.rs

@@ -15,8 +15,13 @@ thread_local! {
 
 /// Borrows the global context and does some operation on it.
 ///
-/// If provided, after the operation is complete, [`rerandomize_global_context`]
-/// is called on the context. If you have some random data available,
+/// If `rerandomize_seed` is provided, then [`rerandomize_global_context`] is called on the context
+/// after the operation. This argument should be provided alongside any operation that uses secret
+/// data (e.g. signing, but not verification). If you have random data available, it should be
+/// provided here; it will be mixed with the current random state as well as the system RNG if it is
+/// available. If you do not have any random data, it is fine to provide all zeros, or a counter, or
+/// a weak source of entropy. This is a defense-in-depth measure to protect against side-channel
+/// attacks, and anything helps (and nothing will hurt).
 pub fn with_global_context<T, Ctx: Context, F: FnOnce(&Secp256k1<Ctx>) -> T>(
     f: F,
     rerandomize_seed: Option<&[u8; 32]>,
@@ -32,8 +37,13 @@ pub fn with_global_context<T, Ctx: Context, F: FnOnce(&Secp256k1<Ctx>) -> T>(
 
 /// Borrows the global context as a raw pointer and does some operation on it.
 ///
-/// If provided, after the operation is complete, [`rerandomize_global_context`]
-/// is called on the context. If you have some random data available,
+/// If `rerandomize_seed` is provided, then [`rerandomize_global_context`] is called on the context
+/// after the operation. This argument should be provided alongside any operation that uses secret
+/// data (e.g. signing, but not verification). If you have random data available, it should be
+/// provided here; it will be mixed with the current random state as well as the system RNG if it is
+/// available. If you do not have any random data, it is fine to provide all zeros, or a counter, or
+/// a weak source of entropy. This is a defense-in-depth measure to protect against side-channel
+/// attacks, and anything helps (and nothing will hurt).
 pub fn with_raw_global_context<T, F: FnOnce(NonNull<ffi::Context>) -> T>(
     f: F,
     rerandomize_seed: Option<&[u8; 32]>,