From 00785022e850e3057642dead61339a0f5e663745 Mon Sep 17 00:00:00 2001 From: appflowy Date: Mon, 25 Jul 2022 12:45:35 +0800 Subject: [PATCH 1/2] chore: add documentation for flowy_grid crate --- .../flowy-grid/src/entities/block_entities.rs | 13 +++ .../flowy-grid/src/entities/cell_entities.rs | 1 + .../flowy-grid/src/entities/field_entities.rs | 21 +++++ .../flowy-grid/src/entities/grid_entities.rs | 2 + .../src/entities/setting_entities.rs | 2 + frontend/rust-lib/flowy-grid/src/event_map.rs | 89 +++++++++++++++++++ .../selection_type_option/select_option.rs | 11 +++ .../flowy-grid/src/services/grid_editor.rs | 1 - .../src/revision/grid_rev.rs | 7 ++ 9 files changed, 146 insertions(+), 1 deletion(-) 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> 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> 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> 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 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, } + +/// Collection of the [GridFieldPB] #[derive(Debug, Default, ProtoBuf)] pub struct RepeatedGridFieldPB { #[pb(index = 1)] @@ -369,6 +382,7 @@ impl TryInto 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, } @@ -429,6 +444,12 @@ impl TryInto 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) -> 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, + /// The selected options for the cell. #[pb(index = 2)] pub select_options: Vec, } + +/// [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, @@ -185,15 +187,20 @@ impl FieldRevision { } } +/// The macro, [impl_type_option] will implement the [TypeOptionDataEntry] for the type that +/// supports serde trait and TryInto 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 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 { From 51617d9eb9f67044291b5bb96dd8e0a95fd61242 Mon Sep 17 00:00:00 2001 From: MikeWallaceDev Date: Mon, 25 Jul 2022 17:17:11 -0400 Subject: [PATCH 2/2] docs: made small changes to grammar --- .../flowy-grid/src/entities/block_entities.rs | 4 +- .../flowy-grid/src/entities/field_entities.rs | 6 +- frontend/rust-lib/flowy-grid/src/event_map.rs | 68 +++++++++---------- .../selection_type_option/select_option.rs | 4 +- .../src/revision/grid_rev.rs | 9 ++- 5 files changed, 44 insertions(+), 47 deletions(-) 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 df09416860..8637e35aed 100644 --- a/frontend/rust-lib/flowy-grid/src/entities/block_entities.rs +++ b/frontend/rust-lib/flowy-grid/src/entities/block_entities.rs @@ -5,7 +5,7 @@ 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 +/// [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. /// /// @@ -30,7 +30,7 @@ impl GridBlockPB { } } -/// [GridRowPB] describes the row belongs to which block and the metadata of the row. +/// [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)] 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 f51685798c..f22998c0f9 100644 --- a/frontend/rust-lib/flowy-grid/src/entities/field_entities.rs +++ b/frontend/rust-lib/flowy-grid/src/entities/field_entities.rs @@ -9,7 +9,7 @@ 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. +/// [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)] @@ -391,7 +391,7 @@ pub struct UpdateFieldTypeOptionPayloadPB { #[pb(index = 2)] pub field_id: String, - /// Check out the [FieldTypeOptionDataPB] for more details. + /// Check out [FieldTypeOptionDataPB] for more details. #[pb(index = 3)] pub type_option_data: Vec, } @@ -444,7 +444,7 @@ impl TryInto for QueryFieldPayloadPB { } } -/// [FieldChangesetPayloadPB] is used to modify the corresponding field. It defines which property of +/// [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 diff --git a/frontend/rust-lib/flowy-grid/src/event_map.rs b/frontend/rust-lib/flowy-grid/src/event_map.rs index c072355f20..f8b3c36d33 100644 --- a/frontend/rust-lib/flowy-grid/src/event_map.rs +++ b/frontend/rust-lib/flowy-grid/src/event_map.rs @@ -50,41 +50,40 @@ pub fn create(grid_manager: Arc) -> Module { pub enum GridEvent { /// [GetGrid] event is used to get the [GridPB] /// - /// The event handler accepts [GridIdPB] and return [GridPB] if there is no errors. - /// + /// 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 [QueryGridBlocksPayloadPB] and return [RepeatedGridBlockPB] - /// if there is no errors. + /// 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 setting. + /// [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 setting. + /// [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 setting. + /// 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 setting. + /// [GetFields] event is used to get the grid's settings. /// - /// The event handler accepts [QueryFieldPayloadPB] and return [RepeatedGridFieldPB] - /// if there is no errors. + /// 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 the field attributes. + /// [UpdateField] event is used to update a field's attributes. /// - /// The event handler accepts [FieldChangesetPayloadPB] and return errors if failed to modify the + /// The event handler accepts a [FieldChangesetPayloadPB] and returns errors if failed to modify the /// field. #[event(input = "FieldChangesetPayloadPB")] UpdateField = 11, @@ -98,28 +97,28 @@ pub enum GridEvent { /// 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 + /// 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 is already exists, the event - /// handler will replace the value with the new field value. + /// [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 new field. [DeleteFieldPayloadPB] is the context that + /// [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. + /// [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 + /// [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. /// @@ -128,17 +127,17 @@ pub enum GridEvent { #[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]. + /// [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 the specific field type. + /// [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 is no errors. + /// Return the [FieldTypeOptionDataPB] if there are no errors. #[event(input = "GridFieldTypeOptionIdPB", output = "FieldTypeOptionDataPB")] GetFieldTypeOption = 23, @@ -146,8 +145,8 @@ pub enum GridEvent { #[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. + /// [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, @@ -157,13 +156,12 @@ pub enum GridEvent { #[event(input = "GridCellIdPB", output = "SelectOptionCellDataPB")] GetSelectOptionCellData = 31, - /// [UpdateSelectOption] event is used to update the FieldTypeOptionData that its field_type is + /// [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, the [SelectOptionChangesetPayloadPB] carries a change that update the name of - /// the option. - /// + /// 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, @@ -187,23 +185,23 @@ pub enum GridEvent { /// [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. + /// 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 concrete type - /// when the FieldType is SingleSelect, DateTime, and MultiSelect. We will discuss the details - /// in [UpdateSelectOptionCell] and [UpdateDateCell] event. + /// 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 the select option cell data. [SelectOptionCellChangesetPayloadPB] + /// [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 the date cell data. [DateChangesetPayloadPB] + /// [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")] 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 ea57931bb8..e9b0b1ed41 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 @@ -12,7 +12,7 @@ use serde::{Deserialize, Serialize}; pub const SELECTION_IDS_SEPARATOR: &str = ","; -/// [SelectOptionPB] represents an option for the single select, and multiple select. +/// [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)] @@ -340,7 +340,7 @@ pub struct SelectOptionCellDataPB { } -/// [SelectOptionChangesetPayloadPB] describes the changes of the FieldTypeOptionData. For the moment, +/// [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 { 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 1bc7139d9a..09056f827d 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 @@ -125,7 +125,6 @@ pub struct FieldRevision { /// 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, @@ -187,15 +186,15 @@ impl FieldRevision { } } -/// The macro, [impl_type_option] will implement the [TypeOptionDataEntry] for the type that -/// supports serde trait and TryInto trait. +/// The macro [impl_type_option] will implement the [TypeOptionDataEntry] for the type that +/// supports the serde trait and the TryInto 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 trait. +/// The macro [impl_type_option] will implement the [TypeOptionDataDeserializer] for the type that +/// supports the serde trait and the TryFrom trait. pub trait TypeOptionDataDeserializer { fn from_json_str(s: &str) -> Self; fn from_protobuf_bytes(bytes: Bytes) -> Self;