From 5b279ac44f0e2fef66d85c7b57581cec2797b0e0 Mon Sep 17 00:00:00 2001
From: guipublic <guipublic@gmail.com>
Date: Wed, 10 Jul 2024 14:20:02 +0000
Subject: [PATCH] document EmbeddedCurvePoint

---
 noir_stdlib/src/embedded_curve_ops.nr | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/noir_stdlib/src/embedded_curve_ops.nr b/noir_stdlib/src/embedded_curve_ops.nr
index c5617094c0a..6ce0835c40f 100644
--- a/noir_stdlib/src/embedded_curve_ops.nr
+++ b/noir_stdlib/src/embedded_curve_ops.nr
@@ -1,7 +1,9 @@
 use crate::ops::arith::{Add, Sub, Neg};
 use crate::cmp::Eq;
 
-// TODO(https://github.com/noir-lang/noir/issues/4931)
+/// A point on the embedded elliptic curve
+/// By definition, the base field of the embedded curve is the scalar field of the proof system curve, i.e the Noir Field.
+/// x and y denotes the Weierstrass coordinates of the point, if is_infinite is false.
 struct EmbeddedCurvePoint {
     x: Field,
     y: Field,
@@ -9,28 +11,35 @@ struct EmbeddedCurvePoint {
 }
 
 impl EmbeddedCurvePoint {
+    /// Elliptic curve point doubling operation
+    /// returns the doubled point of a point P, i.e P+P
     fn double(self) -> EmbeddedCurvePoint {
         embedded_curve_add(self, self)
     }
 
+    /// Returns the null element of the curve; 'the point at infinity'
     fn point_at_infinity() -> EmbeddedCurvePoint {
         EmbeddedCurvePoint { x: 0, y: 0, is_infinite: true }
     }
 }
 
 impl Add for EmbeddedCurvePoint {
+    /// Adds two points P+Q, using the curve addition formula, and also handles point at infinity
     fn add(self, other: EmbeddedCurvePoint) -> EmbeddedCurvePoint { 
         embedded_curve_add(self, other)
     }
 }
 
 impl Sub for EmbeddedCurvePoint {
+    /// Points subtraction operation, using addition and negation
     fn sub(self, other: EmbeddedCurvePoint) -> EmbeddedCurvePoint { 
         self + other.neg()
     }
 }
 
 impl Neg for EmbeddedCurvePoint {
+    /// Negates a point P, i.e returns -P, by negating the y coordinate.
+    /// If the point is at infinity, then the result is also at infinity.
     fn neg(self) -> EmbeddedCurvePoint { 
         EmbeddedCurvePoint {
             x: self.x,
@@ -41,12 +50,15 @@ impl Neg for EmbeddedCurvePoint {
 }
 
 impl Eq for EmbeddedCurvePoint {
+    /// Checks whether two points are equal
     fn eq(self: Self, b: EmbeddedCurvePoint) -> bool {
         (self.is_infinite & b.is_infinite) | ((self.is_infinite == b.is_infinite) & (self.x == b.x) & (self.y == b.y))
     }
 }
 
-// Scalar represented as low and high limbs
+/// Scalar for the embedded curve represented as low and high limbs
+/// By definition, the scalar field of the embedded curve is base field of the proving system curve.
+/// It may not fit into a Field element, so it is represented with two Field elements; its low and high limbs.
 struct EmbeddedCurveScalar {
     lo: Field,
     hi: Field,