chore: rename some function & add more documentation

shared-lib/lib-ot/src/core/delta/builder.rs

@@ -1,7 +1,7 @@
 use crate::core::delta::{trim, Delta};
-use crate::core::operation::{Attributes, PlainTextAttributes};
+use crate::core::operation::{Attributes, PhantomAttributes};
 
-pub type PlainTextDeltaBuilder = DeltaBuilder<PlainTextAttributes>;
+pub type PlainTextDeltaBuilder = DeltaBuilder<PhantomAttributes>;
 
 /// A builder for creating new [Delta] objects.
 ///

shared-lib/lib-ot/src/core/delta/delta.rs

@@ -3,7 +3,7 @@ use crate::errors::{ErrorBuilder, OTError, OTErrorCode};
 use crate::core::delta::{DeltaIterator, MAX_IV_LEN};
 use crate::core::flowy_str::FlowyStr;
 use crate::core::interval::Interval;
-use crate::core::operation::{Attributes, Operation, OperationBuilder, OperationTransformable, PlainTextAttributes};
+use crate::core::operation::{Attributes, Operation, OperationBuilder, OperationTransformable, PhantomAttributes};
 use bytes::Bytes;
 use serde::de::DeserializeOwned;
 use std::{
@@ -14,12 +14,15 @@ use std::{
     str::FromStr,
 };
 
-pub type PlainTextDelta = Delta<PlainTextAttributes>;
+pub type PlainTextDelta = Delta<PhantomAttributes>;
 
 /// A [Delta] contains list of operations that consists of 'Retain', 'Delete' and 'Insert' operation.
 /// Check out the [Operation] for more details. It describes the document as a sequence of
 /// operations.
 ///
+/// If the [T] supports 'serde', that will enable delta to serialize to JSON or deserialize from
+/// a JSON string.
+///
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Delta<T: Attributes> {
     pub ops: Vec<Operation<T>>,
@@ -182,7 +185,7 @@ where
     ///         .insert(", AppFlowy")
     ///         .build();
     ///
-    ///  let after_a = delta_a.to_str().unwrap();
+    ///  let after_a = delta_a.content_str().unwrap();
     ///  let after_b = delta_b.apply(&after_a).unwrap();
     ///  assert_eq!("hello, AppFlowy", &after_b);
     /// ```
@@ -565,7 +568,7 @@ impl<T> Delta<T>
 where
     T: Attributes + DeserializeOwned,
 {
-    pub fn from_delta_str(json: &str) -> Result<Self, OTError> {
+    pub fn from_json_str(json: &str) -> Result<Self, OTError> {
         let delta = serde_json::from_str(json).map_err(|e| {
             tracing::trace!("Deserialize failed: {:?}", e);
             tracing::trace!("{:?}", json);
@@ -576,7 +579,7 @@ where
 
     pub fn from_bytes<B: AsRef<[u8]>>(bytes: B) -> Result<Self, OTError> {
         let json = str::from_utf8(bytes.as_ref())?.to_owned();
-        let val = Self::from_delta_str(&json)?;
+        let val = Self::from_json_str(&json)?;
         Ok(val)
     }
 }
@@ -585,16 +588,16 @@ impl<T> Delta<T>
 where
     T: Attributes + serde::Serialize,
 {
-    pub fn to_delta_str(&self) -> String {
+    pub fn to_json_str(&self) -> String {
         serde_json::to_string(self).unwrap_or_else(|_| "".to_owned())
     }
 
-    pub fn to_str(&self) -> Result<String, OTError> {
+    pub fn content_str(&self) -> Result<String, OTError> {
         self.apply("")
     }
 
-    pub fn to_delta_bytes(&self) -> Bytes {
-        let json = self.to_delta_str();
+    pub fn to_json_bytes(&self) -> Bytes {
+        let json = self.to_json_str();
         Bytes::from(json.into_bytes())
     }
 }

shared-lib/lib-ot/src/core/operation/builder.rs

@@ -1,8 +1,8 @@
-use crate::core::operation::{Attributes, Operation, PlainTextAttributes};
+use crate::core::operation::{Attributes, Operation, PhantomAttributes};
 use crate::rich_text::RichTextAttributes;
 
 pub type RichTextOpBuilder = OperationBuilder<RichTextAttributes>;
-pub type PlainTextOpBuilder = OperationBuilder<PlainTextAttributes>;
+pub type PlainTextOpBuilder = OperationBuilder<PhantomAttributes>;
 
 pub struct OperationBuilder<T: Attributes> {
     ty: Operation<T>,

shared-lib/lib-ot/src/core/operation/operation.rs

@@ -26,7 +26,7 @@ pub trait OperationTransformable {
     ///  let document = PlainTextDeltaBuilder::new().build();
     ///  let delta = PlainTextDeltaBuilder::new().insert("abc").build();
     ///  let new_document = document.compose(&delta).unwrap();
-    ///  assert_eq!(new_document.to_str().unwrap(), "abc".to_owned());
+    ///  assert_eq!(new_document.content_str().unwrap(), "abc".to_owned());
     /// ```
     fn compose(&self, other: &Self) -> Result<Self, OTError>
     where
@@ -65,6 +65,12 @@ pub trait OperationTransformable {
     fn invert(&self, other: &Self) -> Self;
 }
 
+/// Each operation can carry attributes. For example, the [RichTextAttributes] has a list of key/value attributes.
+/// Such as { bold: true, italic: true }.  
+///
+/// Because [Operation] is generic over the T, so you must specify the T. For example, the [PlainTextDelta]. It use
+/// use [PhantomAttributes] as the T. [PhantomAttributes] does nothing, just a phantom.
+///
 pub trait Attributes: Default + Display + Eq + PartialEq + Clone + Debug + OperationTransformable {
     fn is_empty(&self) -> bool {
         true
@@ -80,6 +86,14 @@ pub trait Attributes: Default + Display + Eq + PartialEq + Clone + Debug + Opera
     }
 }
 
+/// [Operation] consists of three types.
+/// * Delete
+/// * Retain
+/// * Insert
+///
+/// The [T] should support serde if you want to serialize/deserialize the operation
+/// to json string. You could check out the operation_serde.rs for more information.
+///
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum Operation<T: Attributes> {
     Delete(usize),
@@ -241,9 +255,7 @@ where
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Retain<T: Attributes> {
-    // #[serde(rename(serialize = "retain", deserialize = "retain"))]
     pub n: usize,
-    // #[serde(skip_serializing_if = "is_empty")]
     pub attributes: T,
 }
 
@@ -318,10 +330,7 @@ where
 
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Insert<T: Attributes> {
-    // #[serde(rename(serialize = "insert", deserialize = "insert"))]
     pub s: FlowyStr,
-
-    // #[serde(skip_serializing_if = "is_empty")]
     pub attributes: T,
 }
 
@@ -402,16 +411,16 @@ where
 }
 
 #[derive(Debug, Clone, Eq, PartialEq, Default, Serialize, Deserialize)]
-pub struct PlainTextAttributes();
-impl fmt::Display for PlainTextAttributes {
+pub struct PhantomAttributes();
+impl fmt::Display for PhantomAttributes {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str("PlainAttributes")
+        f.write_str("PhantomAttributes")
     }
 }
 
-impl Attributes for PlainTextAttributes {}
+impl Attributes for PhantomAttributes {}
 
-impl OperationTransformable for PlainTextAttributes {
+impl OperationTransformable for PhantomAttributes {
     fn compose(&self, _other: &Self) -> Result<Self, OTError> {
         Ok(self.clone())
     }