Merge pull request #707 from AppFlowy-IO/feat/flowy_grid_crate_documentation

chore: add documentation for flowy-grid crate

frontend/rust-lib/flowy-grid/src/entities/block_entities.rs

@@ -4,6 +4,14 @@ use flowy_grid_data_model::parser::NotEmptyStr;
 use flowy_grid_data_model::revision::RowRevision;
 use std::sync::Arc;
 
+
+/// [GridBlockPB] contains list of row ids. The rows here does not contain any data, just the id
+/// of the row. Check out [GridRowPB] for more details.
+///
+///
+/// A grid can have many rows. Rows are therefore grouped into Blocks in order to make
+/// things more efficient.
+///                                        |
 #[derive(Debug, Clone, Default, ProtoBuf)]
 pub struct GridBlockPB {
     #[pb(index = 1)]
@@ -22,6 +30,7 @@ impl GridBlockPB {
     }
 }
 
+/// [GridRowPB] Describes a row. Has the id of the parent Block. Has the metadata of the row.
 #[derive(Debug, Default, Clone, ProtoBuf)]
 pub struct GridRowPB {
     #[pb(index = 1)]
@@ -81,6 +90,8 @@ impl std::convert::From<Vec<GridRowPB>> for RepeatedRowPB {
         Self { items }
     }
 }
+
+/// [RepeatedGridBlockPB] contains list of [GridBlockPB]
 #[derive(Debug, Default, ProtoBuf)]
 pub struct RepeatedGridBlockPB {
     #[pb(index = 1)]
@@ -194,6 +205,8 @@ impl GridBlockChangesetPB {
     }
 }
 
+/// [QueryGridBlocksPayloadPB] is used to query the data of the block that belongs to the grid whose
+/// id is grid_id.
 #[derive(ProtoBuf, Default)]
 pub struct QueryGridBlocksPayloadPB {
     #[pb(index = 1)]

frontend/rust-lib/flowy-grid/src/entities/cell_entities.rs

@@ -119,6 +119,7 @@ impl std::convert::From<Vec<GridCellPB>> for RepeatedCellPB {
     }
 }
 
+///
 #[derive(Debug, Clone, Default, ProtoBuf)]
 pub struct CellChangesetPB {
     #[pb(index = 1)]

frontend/rust-lib/flowy-grid/src/entities/field_entities.rs

@@ -8,6 +8,8 @@ use std::sync::Arc;
 
 use strum_macros::{Display, EnumCount as EnumCountMacro, EnumIter, EnumString};
 
+
+/// [GridFieldPB] defines a Field's attributes. Such as the name, field_type, and width. etc.
 #[derive(Debug, Clone, Default, ProtoBuf)]
 pub struct GridFieldPB {
     #[pb(index = 1)]
@@ -56,6 +58,8 @@ impl std::convert::From<Arc<FieldRevision>> for GridFieldPB {
         GridFieldPB::from(field_rev)
     }
 }
+
+/// [GridFieldIdPB] id of the [Field]
 #[derive(Debug, Clone, Default, ProtoBuf)]
 pub struct GridFieldIdPB {
     #[pb(index = 1)]
@@ -257,6 +261,13 @@ impl TryInto<GridFieldTypeOptionIdParams> for GridFieldTypeOptionIdPB {
     }
 }
 
+/// Certain field types have user-defined options such as color, date format, number format,
+/// or a list of values for a multi-select list. These options are defined within a specialization
+/// of the FieldTypeOption class.
+///
+/// You could check [this](https://appflowy.gitbook.io/docs/essential-documentation/contribute-to-appflowy/architecture/frontend/grid#fieldtype)
+/// for more information.
+///
 #[derive(Debug, Default, ProtoBuf)]
 pub struct FieldTypeOptionDataPB {
     #[pb(index = 1)]
@@ -269,6 +280,8 @@ pub struct FieldTypeOptionDataPB {
     pub type_option_data: Vec<u8>,
 }
 
+
+/// Collection of the [GridFieldPB]
 #[derive(Debug, Default, ProtoBuf)]
 pub struct RepeatedGridFieldPB {
     #[pb(index = 1)]
@@ -364,6 +377,7 @@ impl TryInto<InsertFieldParams> for InsertFieldPayloadPB {
     }
 }
 
+/// [UpdateFieldTypeOptionPayloadPB] is used to update the type option data.
 #[derive(ProtoBuf, Default)]
 pub struct UpdateFieldTypeOptionPayloadPB {
     #[pb(index = 1)]
@@ -372,6 +386,7 @@ pub struct UpdateFieldTypeOptionPayloadPB {
     #[pb(index = 2)]
     pub field_id: String,
 
+    /// Check out [FieldTypeOptionDataPB] for more details.
     #[pb(index = 3)]
     pub type_option_data: Vec<u8>,
 }
@@ -424,6 +439,12 @@ impl TryInto<QueryFieldParams> for QueryFieldPayloadPB {
     }
 }
 
+/// [FieldChangesetPayloadPB] is used to modify the corresponding field. It defines which properties of
+/// the field can be modified.
+///
+/// Pass in None if you don't want to modify a property
+/// Pass in Some(Value) if you want to modify a property
+///
 #[derive(Debug, Clone, Default, ProtoBuf)]
 pub struct FieldChangesetPayloadPB {
     #[pb(index = 1)]

frontend/rust-lib/flowy-grid/src/entities/grid_entities.rs

@@ -2,6 +2,8 @@ use crate::entities::{GridBlockPB, GridFieldIdPB};
 use flowy_derive::{ProtoBuf, ProtoBuf_Enum};
 use flowy_error::ErrorCode;
 use flowy_grid_data_model::parser::NotEmptyStr;
+
+/// [GridPB] describes how many fields and blocks the grid has
 #[derive(Debug, Clone, Default, ProtoBuf)]
 pub struct GridPB {
     #[pb(index = 1)]

frontend/rust-lib/flowy-grid/src/entities/setting_entities.rs

@@ -12,6 +12,8 @@ use std::convert::TryInto;
 use strum::IntoEnumIterator;
 use strum_macros::EnumIter;
 
+
+/// [GridSettingPB] defines the setting options for the grid. Such as the filter, group, and sort.
 #[derive(Eq, PartialEq, ProtoBuf, Debug, Default, Clone)]
 pub struct GridSettingPB {
     #[pb(index = 1)]

frontend/rust-lib/flowy-grid/src/event_map.rs

@@ -42,63 +42,134 @@ pub fn create(grid_manager: Arc<GridManager>) -> Module {
     module
 }
 
+
+/// [GridEvent] defines events that are used to interact with the Grid. You could check [this](https://appflowy.gitbook.io/docs/essential-documentation/contribute-to-appflowy/architecture/backend/protobuf)
+/// out, it includes how to use these annotations: input, output, etc.
 #[derive(Clone, Copy, PartialEq, Eq, Debug, Display, Hash, ProtoBuf_Enum, Flowy_Event)]
 #[event_err = "FlowyError"]
 pub enum GridEvent {
+    /// [GetGrid] event is used to get the [GridPB]
+    ///
+    /// The event handler accepts a [GridIdPB] and returns a [GridPB] if there are no errors.
     #[event(input = "GridIdPB", output = "GridPB")]
     GetGrid = 0,
 
+    /// [GetGridBlocks] event is used to get the grid's block.
+    ///
+    /// The event handler accepts a [QueryGridBlocksPayloadPB] and returns a [RepeatedGridBlockPB]
+    /// if there are no errors.
     #[event(input = "QueryGridBlocksPayloadPB", output = "RepeatedGridBlockPB")]
     GetGridBlocks = 1,
 
+    /// [GetGridSetting] event is used to get the grid's settings.
+    ///
+    /// The event handler accepts [GridIdPB] and return [GridSettingPB]
+    /// if there is no errors.
     #[event(input = "GridIdPB", output = "GridSettingPB")]
     GetGridSetting = 2,
 
+    /// [UpdateGridSetting] event is used to update the grid's settings.
+    ///
+    /// The event handler accepts [GridIdPB] and return errors if failed to modify the grid's settings.
     #[event(input = "GridIdPB", input = "GridSettingChangesetPayloadPB")]
     UpdateGridSetting = 3,
 
+    /// [GetFields] event is used to get the grid's settings.
+    ///
+    /// The event handler accepts a [QueryFieldPayloadPB] and returns a [RepeatedGridFieldPB]
+    /// if there are no errors.
     #[event(input = "QueryFieldPayloadPB", output = "RepeatedGridFieldPB")]
     GetFields = 10,
 
+    /// [UpdateField] event is used to update a field's attributes.
+    ///
+    /// The event handler accepts a [FieldChangesetPayloadPB] and returns errors if failed to modify the
+    /// field.
     #[event(input = "FieldChangesetPayloadPB")]
     UpdateField = 11,
 
+
+    /// [UpdateFieldTypeOption] event is used to update the field's type option data. Certain field
+    /// types have user-defined options such as color, date format, number format, or a list of values
+    /// for a multi-select list. These options are defined within a specialization of the
+    /// FieldTypeOption class.
+    ///
+    /// Check out [this](https://appflowy.gitbook.io/docs/essential-documentation/contribute-to-appflowy/architecture/frontend/grid#fieldtype)
+    /// for more information.
+    ///
+    /// The event handler accepts a [UpdateFieldTypeOptionPayloadPB] and returns errors if failed to modify the
+    /// field.
     #[event(input = "UpdateFieldTypeOptionPayloadPB")]
     UpdateFieldTypeOption = 12,
 
+    /// [InsertField] event is used to insert a new Field. If the Field already exists, the event
+    /// handler will replace the value with the new Field value.
     #[event(input = "InsertFieldPayloadPB")]
     InsertField = 13,
 
+    /// [DeleteField] event is used to delete a Field. [DeleteFieldPayloadPB] is the context that
+    /// is used to delete the field from the Grid.
     #[event(input = "DeleteFieldPayloadPB")]
     DeleteField = 14,
 
+    /// [SwitchToField] event is used to update the current Field's type.
+    /// It will insert a new FieldTypeOptionData if the new FieldType doesn't exist before, otherwise
+    /// reuse the existing FieldTypeOptionData. You could check the [GridRevisionPad] for more details.
     #[event(input = "EditFieldPayloadPB", output = "FieldTypeOptionDataPB")]
     SwitchToField = 20,
 
+    /// [DuplicateField] event is used to duplicate a Field. The duplicated field data is kind of
+    /// deep copy of the target field. The passed in [DuplicateFieldPayloadPB] is the context that is
+    /// used to duplicate the field.
+    ///
+    /// Return errors if failed to duplicate the field.
+    ///
     #[event(input = "DuplicateFieldPayloadPB")]
     DuplicateField = 21,
 
+    /// [MoveItem] event is used to move an item. For the moment, Item has two types defined in
+    /// [MoveItemTypePB].
     #[event(input = "MoveItemPayloadPB")]
     MoveItem = 22,
 
+    /// [GetFieldTypeOption] event is used to get the FieldTypeOption data for a specific field type.
+    ///
+    /// Check out the [FieldTypeOptionDataPB] for more details. If the [FieldTypeOptionData] does exist
+    /// for the target type, the [TypeOptionBuilder] will create the default data for that type.
+    ///
+    /// Return the [FieldTypeOptionDataPB] if there are no errors.
     #[event(input = "GridFieldTypeOptionIdPB", output = "FieldTypeOptionDataPB")]
     GetFieldTypeOption = 23,
 
+    /// [CreateFieldTypeOption] event is used to create a new FieldTypeOptionData.
     #[event(input = "CreateFieldPayloadPB", output = "FieldTypeOptionDataPB")]
     CreateFieldTypeOption = 24,
 
+    /// [NewSelectOption] event is used to create a new select option. Returns a [SelectOptionPB] if
+    /// there are no errors.
     #[event(input = "CreateSelectOptionPayloadPB", output = "SelectOptionPB")]
     NewSelectOption = 30,
 
+    /// [GetSelectOptionCellData] event is used to get the select option data for cell editing.
+    /// [GridCellIdPB] locate which cell data that will be read from. The return value, [SelectOptionCellDataPB]
+    /// contains the available options and the currently selected options.
     #[event(input = "GridCellIdPB", output = "SelectOptionCellDataPB")]
     GetSelectOptionCellData = 31,
 
+    /// [UpdateSelectOption] event is used to update a FieldTypeOptionData whose field_type is
+    /// FieldType::SingleSelect or FieldType::MultiSelect.
+    ///
+    /// This event may trigger the GridNotification::DidUpdateCell event.
+    /// For example, GridNotification::DidUpdateCell will be triggered if the [SelectOptionChangesetPayloadPB] 
+    /// carries a change that updates the name of the option.
     #[event(input = "SelectOptionChangesetPayloadPB")]
     UpdateSelectOption = 32,
 
     #[event(input = "CreateRowPayloadPB", output = "GridRowPB")]
     CreateRow = 50,
 
+    /// [GetRow] event is used to get the row data,[GridRowPB]. [OptionalRowPB] is a wrapper that enables
+    /// to return a nullable row data.
     #[event(input = "GridRowIdPB", output = "OptionalRowPB")]
     GetRow = 51,
 
@@ -111,12 +182,28 @@ pub enum GridEvent {
     #[event(input = "GridCellIdPB", output = "GridCellPB")]
     GetCell = 70,
 
+    /// [UpdateCell] event is used to update the cell content. The passed in data, [CellChangesetPB],
+    /// carries the changes that will be applied to the cell content by calling `update_cell` function.
+    ///
+    /// The 'content' property of the [CellChangesetPB] is a String type. It can be used directly if the
+    /// cell uses string data. For example, the TextCell or NumberCell.
+    ///
+    /// But,it can be treated as a generic type, because we can use [serde] to deserialize the string
+    /// into a specific data type. For the moment, the 'content' will be deserialized to a concrete type
+    /// when the FieldType is SingleSelect, DateTime, and MultiSelect. Please see
+    /// the [UpdateSelectOptionCell] and [UpdateDateCell] events for more details.
     #[event(input = "CellChangesetPB")]
     UpdateCell = 71,
 
+    /// [UpdateSelectOptionCell] event is used to update a select option cell's data. [SelectOptionCellChangesetPayloadPB]
+    /// contains options that will be deleted or inserted. It can be cast to [CellChangesetPB] that
+    /// will be used by the `update_cell` function.
     #[event(input = "SelectOptionCellChangesetPayloadPB")]
     UpdateSelectOptionCell = 72,
 
+    /// [UpdateDateCell] event is used to update a date cell's data. [DateChangesetPayloadPB]
+    /// contains the date and the time string. It can be cast to [CellChangesetPB] that
+    /// will be used by the `update_cell` function.
     #[event(input = "DateChangesetPayloadPB")]
     UpdateDateCell = 80,
 }

frontend/rust-lib/flowy-grid/src/services/field/type_options/selection_type_option/select_option.rs

@@ -11,6 +11,8 @@ use serde::{Deserialize, Serialize};
 
 pub const SELECTION_IDS_SEPARATOR: &str = ",";
 
+
+/// [SelectOptionPB] represents an option for a single select, and multiple select.
 #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, ProtoBuf)]
 pub struct SelectOptionPB {
     #[pb(index = 1)]
@@ -322,15 +324,24 @@ impl SelectOptionCellChangeset {
     }
 }
 
+
+/// [SelectOptionCellDataPB] contains a list of user's selected options and a list of all the options
+/// that the cell can use.
 #[derive(Clone, Debug, Default, Serialize, Deserialize, ProtoBuf)]
 pub struct SelectOptionCellDataPB {
+
+    /// The available options that the cell can use.
     #[pb(index = 1)]
     pub options: Vec<SelectOptionPB>,
 
+    /// The selected options for the cell.
     #[pb(index = 2)]
     pub select_options: Vec<SelectOptionPB>,
 }
 
+
+/// [SelectOptionChangesetPayloadPB] describes the changes of a FieldTypeOptionData. For the moment,
+/// it is used by [MultiSelectTypeOptionPB] and [SingleSelectTypeOptionPB].
 #[derive(Clone, Debug, Default, ProtoBuf)]
 pub struct SelectOptionChangesetPayloadPB {
     #[pb(index = 1)]

frontend/rust-lib/flowy-grid/src/services/grid_editor.rs

@@ -103,7 +103,6 @@ impl GridRevisionEditor {
                 .modify(|grid| {
                     let builder = type_option_builder_from_bytes(type_option_data, &field.field_type);
                     let field_rev = FieldBuilder::from_field(field, builder).build();
-
                     Ok(grid.create_field_rev(field_rev, start_field_id)?)
                 })
                 .await?;

shared-lib/flowy-grid-data-model/src/revision/grid_rev.rs

@@ -123,6 +123,7 @@ pub struct FieldRevision {
     /// type_options contains key/value pairs
     /// key: id of the FieldType
     /// value: type option data that can be parsed into specified TypeOptionStruct.
+    ///
     /// For example, CheckboxTypeOption, MultiSelectTypeOption etc.
     #[serde(with = "indexmap::serde_seq")]
     pub type_options: IndexMap<String, String>,
@@ -185,15 +186,20 @@ impl FieldRevision {
     }
 }
 
+/// The macro [impl_type_option] will implement the [TypeOptionDataEntry] for the type that
+/// supports the serde trait and the TryInto<Bytes> trait.
 pub trait TypeOptionDataEntry {
     fn json_str(&self) -> String;
     fn protobuf_bytes(&self) -> Bytes;
 }
 
+/// The macro [impl_type_option] will implement the [TypeOptionDataDeserializer] for the type that
+/// supports the serde trait and the TryFrom<Bytes> trait.
 pub trait TypeOptionDataDeserializer {
     fn from_json_str(s: &str) -> Self;
     fn from_protobuf_bytes(bytes: Bytes) -> Self;
 }
+
 pub type FieldId = String;
 #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
 pub struct RowRevision {