Re-add docs that were deleted

Author: richardpringle

poly-commitment/src/ipa.rs

@@ -70,7 +70,8 @@ pub struct SRS<G> {
     lagrange_bases: HashMapCache<usize, Vec<PolyComm<G>>>,
     #[cfg(not(feature = "std"))]
     #[serde(skip)]
-    lagrange_bases: alloc::rc::Rc<core::cell::RefCell<HashMap<usize, Vec<PolyComm<G>>>>>,
+    lagrange_bases:
+        alloc::rc::Rc<core::cell::RefCell<HashMap<usize, alloc::rc::Rc<Vec<PolyComm<G>>>>>>,
 }
 
 #[cfg(not(feature = "std"))]
@@ -79,28 +80,23 @@ trait GetOrGenExt<G> {
         &self,
         key: usize,
         generator: F,
-    ) -> &Vec<PolyComm<G>>;
+    ) -> alloc::rc::Rc<Vec<PolyComm<G>>>;
 }
 
 #[cfg(not(feature = "std"))]
-#[allow(unsafe_code)]
-impl<G> GetOrGenExt<G> for alloc::rc::Rc<core::cell::RefCell<HashMap<usize, Vec<PolyComm<G>>>>> {
+impl<G> GetOrGenExt<G>
+    for alloc::rc::Rc<core::cell::RefCell<HashMap<usize, alloc::rc::Rc<Vec<PolyComm<G>>>>>>
+{
     fn get_or_generate<F: FnOnce() -> Vec<PolyComm<G>>>(
         &self,
         key: usize,
         generator: F,
-    ) -> &Vec<PolyComm<G>> {
+    ) -> alloc::rc::Rc<Vec<PolyComm<G>>> {
         let mut map = self.borrow_mut();
-        if !map.contains_key(&key) {
-            map.insert(key, generator());
-        }
-        drop(map);
-
-        // SAFETY: We never remove entries from the map, and the Rc<RefCell<HashMap>>
-        // lives as long as the SRS. The reference is valid as long as the entry exists.
-        let map = self.borrow();
-        let ptr = map.get(&key).unwrap() as *const Vec<PolyComm<G>>;
-        unsafe { &*ptr }
+        let entry = map
+            .entry(key)
+            .or_insert_with(|| alloc::rc::Rc::new(generator()));
+        alloc::rc::Rc::clone(entry)
     }
 }
 
@@ -158,7 +154,7 @@ impl<G> SRS<G> {
     #[cfg(not(feature = "std"))]
     pub const fn lagrange_bases(
         &self,
-    ) -> &alloc::rc::Rc<core::cell::RefCell<HashMap<usize, Vec<PolyComm<G>>>>> {
+    ) -> &alloc::rc::Rc<core::cell::RefCell<HashMap<usize, alloc::rc::Rc<Vec<PolyComm<G>>>>>> {
         &self.lagrange_bases
     }
 }
@@ -597,6 +593,7 @@ impl<G> SRSTrait<G> for SRS<G>
 where
     G: CommitmentCurve,
 {
+    /// The maximum polynomial degree that can be committed to
     fn max_poly_size(&self) -> usize {
         self.g.len()
     }
@@ -624,6 +621,9 @@ where
         })
     }
 
+    /// Turns a non-hiding polynomial commitment into a hiding polynomial
+    /// commitment. Transforms each given `<a, G>` into `(<a, G> + wH, w)` with
+    /// a random `w` per commitment.
     #[cfg(feature = "std")]
     fn mask(
         &self,