chore: update documentation for type option cell-related traits (#5207)

This commit is contained in:
Richard Shiue 2024-04-27 10:20:32 +08:00 committed by GitHub
parent d467dcd68a
commit d4278a7549
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 49 additions and 65 deletions

View File

@ -14,25 +14,23 @@ use crate::services::group::make_no_status_group;
/// Decode the opaque cell data into readable format content /// Decode the opaque cell data into readable format content
pub trait CellDataDecoder: TypeOption { pub trait CellDataDecoder: TypeOption {
/// Tries to decode the [Cell] to `decoded_field_type`'s cell data. Sometimes, the `field_type` /// Decodes the [Cell] into a `CellData` of this `TypeOption`'s field type.
/// of the `Field` is not equal to the `decoded_field_type`(This happened When switching /// The `field_type` of the `Cell` should be the same as that of this
/// the field type of the `Field` to another field type). So the cell data is need to do /// `TypeOption`.
/// some transformation.
///
/// For example, the current field type of the `Field` is a checkbox. When switching the field
/// type from the checkbox to single select, it will create two new options,`Yes` and `No`, if they don't exist.
/// But the data of the cell doesn't change. We can't iterate all the rows to transform the cell
/// data that can be parsed by the current field type. One approach is to transform the cell data
/// when reading.
fn decode_cell(&self, cell: &Cell) -> FlowyResult<<Self as TypeOption>::CellData>;
/// Transform the cell data from one field type to another
/// ///
/// # Arguments /// # Arguments
/// ///
/// * `cell`: the cell in the current field type /// * `cell`: the cell to be decoded
/// * `transformed_field_type`: the cell will be transformed to the is field type's cell data. ///
/// current `TypeOption` field type. fn decode_cell(&self, cell: &Cell) -> FlowyResult<<Self as TypeOption>::CellData>;
/// Decodes the [Cell] that is of a particular field type into a `CellData` of this `TypeOption`'s field type.
///
/// # Arguments
///
/// * `cell`: the cell to be decoded
/// * `from_field_type`: the original field type of the `cell``
/// * `field`: the `Field` which this cell belongs to
/// ///
fn decode_cell_with_transform( fn decode_cell_with_transform(
&self, &self,
@ -43,26 +41,28 @@ pub trait CellDataDecoder: TypeOption {
None None
} }
/// Decode the cell data to readable `String` /// Decode the cell data to a readable `String`
/// For example, The string of the Multi-Select cell will be a list of the option's name /// For example, The string of the Multi-Select cell will be a list of the option's name
/// separated by a comma. /// separated by a comma.
///
fn stringify_cell_data(&self, cell_data: <Self as TypeOption>::CellData) -> String; fn stringify_cell_data(&self, cell_data: <Self as TypeOption>::CellData) -> String;
/// Decode the cell into f64 /// Decode the cell into f64
/// Different field type has different way to decode the cell data into f64 /// Different field type has different way to decode the cell data into f64
/// If the field type doesn't support to decode the cell data into f64, it will return None /// If the field type doesn't support to decode the cell data into f64, it will return None
///
fn numeric_cell(&self, cell: &Cell) -> Option<f64>; fn numeric_cell(&self, cell: &Cell) -> Option<f64>;
} }
pub trait CellDataChangeset: TypeOption { pub trait CellDataChangeset: TypeOption {
/// The changeset is able to parse into the concrete data struct if `TypeOption::CellChangeset` /// Applies a changeset to a given cell, returning the new `Cell` and
/// implements the `FromCellChangesetString` trait e.g. /// `TypeOption::CellData`
/// SelectOptionCellChangeset, DateCellChangeset
/// ///
/// # Arguments /// # Arguments
/// ///
/// * `changeset`: the cell changeset that represents the changes of the cell. /// * `changeset`: the cell changeset that represents the changes of the cell.
/// * `cell`: the data of the cell. It will be None if the cell does not contain any data. /// * `cell`: the data of the cell. It might be `None`` if the cell does not contain any data.
///
fn apply_changeset( fn apply_changeset(
&self, &self,
changeset: <Self as TypeOption>::CellChangeset, changeset: <Self as TypeOption>::CellChangeset,
@ -70,12 +70,17 @@ pub trait CellDataChangeset: TypeOption {
) -> FlowyResult<(Cell, <Self as TypeOption>::CellData)>; ) -> FlowyResult<(Cell, <Self as TypeOption>::CellData)>;
} }
/// changeset: It will be deserialized into specific data base on the FieldType. /// Applies a cell changeset to a cell
/// For example, ///
/// FieldType::RichText => String /// Check `TypeOptionCellDataHandler::handle_cell_changeset` for more details
/// FieldType::SingleSelect => SelectOptionChangeset ///
/// # Arguments
///
/// * `changeset`: The cell changeset to be applied
/// * `cell`: The cell to be changed
/// * `field`: The field which the cell belongs to
/// * `cell_data_cache`: for quickly getting cell data
/// ///
/// cell_rev: It will be None if the cell does not contain any data.
pub fn apply_cell_changeset( pub fn apply_cell_changeset(
changeset: BoxAny, changeset: BoxAny,
cell: Option<Cell>, cell: Option<Cell>,
@ -88,56 +93,37 @@ pub fn apply_cell_changeset(
} }
} }
pub fn get_cell_protobuf( /// Gets the cell protobuf of a cell, returning default when parsing isn't
cell: &Cell, /// successful.
field: &Field,
cell_cache: Option<CellCache>,
) -> CellProtobufBlob {
match try_decode_cell_to_cell_protobuf(cell, field, cell_cache) {
Ok(cell_bytes) => cell_bytes,
Err(e) => {
tracing::error!("Decode cell data failed, {:?}", e);
CellProtobufBlob::default()
},
}
}
/// Decode the opaque cell data from one field type to another using the corresponding `TypeOption`
/// ///
/// The cell data might become an empty string depends on the to_field_type's `TypeOption` /// Check `TypeOptionCellDataHandler::handle_get_protobuf_cell_data` for more
/// support transform the from_field_type's cell data or not. /// details
/// ///
/// # Arguments /// # Arguments
/// ///
/// * `cell`: the opaque cell string that can be decoded by corresponding structs. /// * `cell`: The cell from which the protobuf should be created
/// * `from_field_type`: the original field type of the passed-in cell data. Check the `TypeCellData` /// * `field`: The field which the cell belongs to
/// that is used to save the origin field type of the cell data. /// * `cell_data_cache`: for quickly getting cell data
/// * `to_field_type`: decode the passed-in cell data to this field type. It will use the to_field_type's
/// TypeOption to decode this cell data.
/// * `field`: used to get the corresponding TypeOption for the specified field type.
/// ///
/// returns: CellBytes pub fn get_cell_protobuf(
///
pub fn try_decode_cell_to_cell_protobuf(
cell: &Cell, cell: &Cell,
field: &Field, field: &Field,
cell_data_cache: Option<CellCache>, cell_data_cache: Option<CellCache>,
) -> FlowyResult<CellProtobufBlob> { ) -> CellProtobufBlob {
match TypeOptionCellExt::new(field, cell_data_cache).get_type_option_cell_data_handler() { match TypeOptionCellExt::new(field, cell_data_cache).get_type_option_cell_data_handler() {
None => Ok(CellProtobufBlob::default()), None => CellProtobufBlob::default(),
Some(handler) => handler.handle_get_protobuf_cell_data(cell, field), Some(handler) => handler
.handle_get_protobuf_cell_data(cell, field)
.unwrap_or_default(),
} }
} }
/// Returns a string that represents the current field_type's cell data. /// Returns a string that represents the cell's data. Using the field type of the cell and the field's type option, create a TypeOptionCellDataHandler. Then,
/// For example, a Multi-Select cell will be represented by a list of the options' names /// get the cell data in that field type and stringify it.
/// separated by commas.
/// ///
/// # Arguments /// # Arguments
/// ///
/// * `cell`: the opaque cell string that can be decoded by corresponding structs /// * `cell`: the opaque cell string that can be decoded by corresponding structs
/// * `to_field_type`: the cell will be decoded to this field type's cell data.
/// * `from_field_type`: the original field type of the passed-in cell data.
/// * `field`: used to get the corresponding TypeOption for the specified field type. /// * `field`: used to get the corresponding TypeOption for the specified field type.
/// ///
pub fn stringify_cell(cell: &Cell, field: &Field) -> String { pub fn stringify_cell(cell: &Cell, field: &Field) -> String {

View File

@ -78,12 +78,10 @@ pub trait TypeOptionCellDataHandler: Send + Sync + 'static {
fn handle_cell_filter(&self, field: &Field, cell: &Cell, filter: &BoxAny) -> bool; fn handle_cell_filter(&self, field: &Field, cell: &Cell, filter: &BoxAny) -> bool;
/// Format the cell to string using the passed-in [FieldType] and [Field]. /// Stringify the cell according to the field_type of this handler.
/// The [Cell] is generic, so we need to know the [FieldType] and [Field] to format the cell.
///
/// For example, the field type of the [TypeOptionCellDataHandler] is [FieldType::Date], and
/// the if field_type is [FieldType::RichText], then the string would be something like "Mar 14, 2022".
/// ///
/// For example, if the field type of the [TypeOptionCellDataHandler] is [FieldType::Date], then the string will be a formatted string according to
/// the type option of the field. It might be something like "Mar 14, 2022".
fn handle_stringify_cell(&self, cell: &Cell, field: &Field) -> String; fn handle_stringify_cell(&self, cell: &Cell, field: &Field) -> String;
fn handle_numeric_cell(&self, cell: &Cell) -> Option<f64>; fn handle_numeric_cell(&self, cell: &Cell) -> Option<f64>;