Skip to content

Bring projects, wikis, and teams together with AI. AppFlowy is the AI collaborative workspace where you achieve more without losing control of your data. The leading open source Notion alternative.

chore: add documentation for flowy_grid crate

appflowy00785022e850
diff --git a/frontend/rust-lib/flowy-grid/src/entities/block_entities.rs b/frontend/rust-lib/flowy-grid/src/entities/block_entities.rs
index df2192c77d..df09416860 100644
--- a/frontend/rust-lib/flowy-grid/src/entities/block_entities.rs
+++ b/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 rows. The row 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 the row belongs to which block and 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)]
diff --git a/frontend/rust-lib/flowy-grid/src/entities/cell_entities.rs b/frontend/rust-lib/flowy-grid/src/entities/cell_entities.rs
index 30e8d65018..d128c8d76f 100644
--- a/frontend/rust-lib/flowy-grid/src/entities/cell_entities.rs
+++ b/frontend/rust-lib/flowy-grid/src/entities/cell_entities.rs
@@ -121,6 +121,7 @@ impl std::convert::From<Vec<GridCellPB>> for RepeatedCellPB {
}
}
+///
#[derive(Debug, Clone, Default, ProtoBuf)]
pub struct CellChangesetPB {
#[pb(index = 1)]
diff --git a/frontend/rust-lib/flowy-grid/src/entities/field_entities.rs b/frontend/rust-lib/flowy-grid/src/entities/field_entities.rs
index 760b820233..f51685798c 100644
--- a/frontend/rust-lib/flowy-grid/src/entities/field_entities.rs
+++ b/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 the 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)]
@@ -262,6 +266,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)]
@@ -274,6 +285,8 @@ pub struct FieldTypeOptionDataPB {
pub type_option_data: Vec<u8>,
}
+
+/// Collection of the [GridFieldPB]
#[derive(Debug, Default, ProtoBuf)]
pub struct RepeatedGridFieldPB {
#[pb(index = 1)]
@@ -369,6 +382,7 @@ impl TryInto<InsertFieldParams> for InsertFieldPayloadPB {
}
}
+/// [UpdateFieldTypeOptionPayloadPB] is used to update the type option data.
#[derive(ProtoBuf, Default)]
pub struct UpdateFieldTypeOptionPayloadPB {
#[pb(index = 1)]
@@ -377,6 +391,7 @@ pub struct UpdateFieldTypeOptionPayloadPB {
#[pb(index = 2)]
pub field_id: String,
+ /// Check out the [FieldTypeOptionDataPB] for more details.
#[pb(index = 3)]
pub type_option_data: Vec<u8>,
}
@@ -429,6 +444,12 @@ impl TryInto<QueryFieldParams> for QueryFieldPayloadPB {
}
}
+/// [FieldChangesetPayloadPB] is used to modify the corresponding field. It defines which property 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)]
diff --git a/frontend/rust-lib/flowy-grid/src/entities/grid_entities.rs b/frontend/rust-lib/flowy-grid/src/entities/grid_entities.rs
index 1be0412503..49278afc54 100644
--- a/frontend/rust-lib/flowy-grid/src/entities/grid_entities.rs
+++ b/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)]
diff --git a/frontend/rust-lib/flowy-grid/src/entities/setting_entities.rs b/frontend/rust-lib/flowy-grid/src/entities/setting_entities.rs
index 9272cfe46d..697910ccad 100644
--- a/frontend/rust-lib/flowy-grid/src/entities/setting_entities.rs
+++ b/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)]
diff --git a/frontend/rust-lib/flowy-grid/src/event_map.rs b/frontend/rust-lib/flowy-grid/src/event_map.rs
index 9165d8f7f9..c072355f20 100644
--- a/frontend/rust-lib/flowy-grid/src/event_map.rs
+++ b/frontend/rust-lib/flowy-grid/src/event_map.rs
@@ -42,63 +42,136 @@ 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 [GridIdPB] and return [GridPB] if there is no errors.
+ ///
#[event(input = "GridIdPB", output = "GridPB")]
GetGrid = 0,
+ /// [GetGridBlocks] event is used to get the grid's block.
+ ///
+ /// The event handler accepts [QueryGridBlocksPayloadPB] and return [RepeatedGridBlockPB]
+ /// if there is no errors.
#[event(input = "QueryGridBlocksPayloadPB", output = "RepeatedGridBlockPB")]
GetGridBlocks = 1,
+ /// [GetGridSetting] event is used to get the grid's setting.
+ ///
+ /// 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 setting.
+ ///
+ /// The event handler accepts [GridIdPB] and return errors if failed to modify the grid's setting.
#[event(input = "GridIdPB", input = "GridSettingChangesetPayloadPB")]
UpdateGridSetting = 3,
+ /// [GetFields] event is used to get the grid's setting.
+ ///
+ /// The event handler accepts [QueryFieldPayloadPB] and return [RepeatedGridFieldPB]
+ /// if there is no errors.
#[event(input = "QueryFieldPayloadPB", output = "RepeatedGridFieldPB")]
GetFields = 10,
+ /// [UpdateField] event is used to update the field attributes.
+ ///
+ /// The event handler accepts [FieldChangesetPayloadPB] and return 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 [UpdateFieldTypeOptionPayloadPB] and return errors if failed to modify the
+ /// field.
#[event(input = "UpdateFieldTypeOptionPayloadPB")]
UpdateFieldTypeOption = 12,
+ /// [InsertField] event is used to insert a new field. If the field is 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 new 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 the 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 the item. For the moment, the item has two types defined in
+ /// the [MoveItemTypePB].
#[event(input = "MoveItemPayloadPB")]
MoveItem = 22,
+ /// [GetFieldTypeOption] event is used to get the FieldTypeOption data for the 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 is 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. Return the [SelectOptionPB] if
+ /// there is 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 the FieldTypeOptionData that its field_type is
+ /// FieldType::SingleSelect or FieldType::MultiSelect.
+ ///
+ /// This event may trigger the GridNotification::DidUpdateCell event.
+ /// For example, the [SelectOptionChangesetPayloadPB] carries a change that update 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 +184,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 String type. It can be used directly if the
+ /// cell use 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 concrete type
+ /// when the FieldType is SingleSelect, DateTime, and MultiSelect. We will discuss the details
+ /// in [UpdateSelectOptionCell] and [UpdateDateCell] event.
#[event(input = "CellChangesetPB")]
UpdateCell = 71,
+ /// [UpdateSelectOptionCell] event is used to update the select option cell 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 the date cell 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,
}
diff --git a/frontend/rust-lib/flowy-grid/src/services/field/type_options/selection_type_option/select_option.rs b/frontend/rust-lib/flowy-grid/src/services/field/type_options/selection_type_option/select_option.rs
index 8f441e1755..ea57931bb8 100644
--- a/frontend/rust-lib/flowy-grid/src/services/field/type_options/selection_type_option/select_option.rs
+++ b/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 the 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 the FieldTypeOptionData. For the moment,
+/// it is used by [MultiSelectTypeOptionPB] and [SingleSelectTypeOptionPB].
#[derive(Clone, Debug, Default, ProtoBuf)]
pub struct SelectOptionChangesetPayloadPB {
#[pb(index = 1)]
diff --git a/frontend/rust-lib/flowy-grid/src/services/grid_editor.rs b/frontend/rust-lib/flowy-grid/src/services/grid_editor.rs
index 5c7436022e..a7921041bc 100644
--- a/frontend/rust-lib/flowy-grid/src/services/grid_editor.rs
+++ b/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?;
diff --git a/shared-lib/flowy-grid-data-model/src/revision/grid_rev.rs b/shared-lib/flowy-grid-data-model/src/revision/grid_rev.rs
index 2298eb485f..1bc7139d9a 100644
--- a/shared-lib/flowy-grid-data-model/src/revision/grid_rev.rs
+++ b/shared-lib/flowy-grid-data-model/src/revision/grid_rev.rs
@@ -123,7 +123,9 @@ 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 +187,20 @@ impl FieldRevision {
}
}
+/// The macro, [impl_type_option] will implement the [TypeOptionDataEntry] for the type that
+/// supports serde trait and 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 serde trait and 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 {