docs: improve documentation (#3265)

frontend/appflowy_flutter/lib/user/application/auth/auth_service.dart

@@ -12,8 +12,20 @@ class AuthServiceMapKeys {
   static const String deviceId = 'device_id';
 }
 
+/// `AuthService` is an abstract class that defines methods related to user authentication.
+///
+/// This service provides various methods for user sign-in, sign-up,
+/// OAuth-based registration, and other related functionalities.
 abstract class AuthService {
+  /// Authenticates a user with their email and password.
+  ///
+  /// - `email`: The email address of the user.
+  /// - `password`: The password of the user.
+  /// - `authType`: The type of authentication (optional).
+  /// - `params`: Additional parameters for authentication (optional).
+  ///
   /// Returns [UserProfilePB] if the user is authenticated, otherwise returns [FlowyError].
+
   Future<Either<FlowyError, UserProfilePB>> signIn({
     required String email,
     required String password,
@@ -21,6 +33,14 @@ abstract class AuthService {
     Map<String, String> params,
   });
 
+  /// Registers a new user with their name, email, and password.
+  ///
+  /// - `name`: The name of the user.
+  /// - `email`: The email address of the user.
+  /// - `password`: The password of the user.
+  /// - `authType`: The type of authentication (optional).
+  /// - `params`: Additional parameters for registration (optional).
+  ///
   /// Returns [UserProfilePB] if the user is authenticated, otherwise returns [FlowyError].
   Future<Either<FlowyError, UserProfilePB>> signUp({
     required String name,
@@ -30,27 +50,46 @@ abstract class AuthService {
     Map<String, String> params,
   });
 
+  /// Registers a new user with an OAuth platform.
+  ///
+  /// - `platform`: The OAuth platform name.
+  /// - `authType`: The type of authentication (optional).
+  /// - `params`: Additional parameters for OAuth registration (optional).
   ///
+  /// Returns [UserProfilePB] if the user is authenticated, otherwise returns [FlowyError].
   Future<Either<FlowyError, UserProfilePB>> signUpWithOAuth({
     required String platform,
     AuthTypePB authType,
     Map<String, String> params,
   });
 
-  /// Returns a default [UserProfilePB]
+  /// Registers a user as a guest.
+  ///
+  /// - `authType`: The type of authentication (optional).
+  /// - `params`: Additional parameters for guest registration (optional).
+  ///
+  /// Returns a default [UserProfilePB].
   Future<Either<FlowyError, UserProfilePB>> signUpAsGuest({
     AuthTypePB authType,
     Map<String, String> params,
   });
 
+  /// Authenticates a user with a magic link sent to their email.
+  ///
+  /// - `email`: The email address of the user.
+  /// - `params`: Additional parameters for authentication with magic link (optional).
+  ///
+  /// Returns [UserProfilePB] if the user is authenticated, otherwise returns [FlowyError].
   Future<Either<FlowyError, UserProfilePB>> signInWithMagicLink({
     required String email,
     Map<String, String> params,
   });
 
-  ///
+  /// Signs out the currently authenticated user.
   Future<void> signOut();
 
-  /// Returns [UserProfilePB] if the user has sign in, otherwise returns null.
+  /// Retrieves the currently authenticated user's profile.
+  ///
+  /// Returns [UserProfilePB] if the user has signed in, otherwise returns [FlowyError].
   Future<Either<FlowyError, UserProfilePB>> getUser();
 }

frontend/rust-lib/flowy-core/src/integrate/server.rs

@@ -23,7 +23,7 @@ use flowy_user::event_map::UserCloudServiceProvider;
 use flowy_user::services::database::{
   get_user_profile, get_user_workspace, open_collab_db, open_user_db,
 };
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 use flowy_user_deps::entities::*;
 use lib_infra::future::FutureResult;
 
@@ -59,7 +59,7 @@ impl Display for ServerProviderType {
 /// The [AppFlowyServerProvider] provides list of [AppFlowyServer] base on the [AuthType]. Using
 /// the auth type, the [AppFlowyServerProvider] will create a new [AppFlowyServer] if it doesn't
 /// exist.
-/// Each server implements the [AppFlowyServer] trait, which provides the [UserService], etc.
+/// Each server implements the [AppFlowyServer] trait, which provides the [UserCloudService], etc.
 pub struct AppFlowyServerProvider {
   config: AppFlowyCoreConfig,
   provider_type: RwLock<ServerProviderType>,
@@ -68,7 +68,7 @@ pub struct AppFlowyServerProvider {
   enable_sync: RwLock<bool>,
   encryption: RwLock<Arc<dyn AppFlowyEncryption>>,
   store_preferences: Weak<StorePreferences>,
-  cache_user_service: RwLock<HashMap<ServerProviderType, Arc<dyn UserService>>>,
+  cache_user_service: RwLock<HashMap<ServerProviderType, Arc<dyn UserCloudService>>>,
 }
 
 impl AppFlowyServerProvider {
@@ -192,9 +192,9 @@ impl UserCloudServiceProvider for AppFlowyServerProvider {
     *self.device_id.write() = device_id.to_string();
   }
 
-  /// Returns the [UserService] base on the current [ServerProviderType].
+  /// Returns the [UserCloudService] base on the current [ServerProviderType].
   /// Creates a new [AppFlowyServer] if it doesn't exist.
-  fn get_user_service(&self) -> Result<Arc<dyn UserService>, FlowyError> {
+  fn get_user_service(&self) -> Result<Arc<dyn UserCloudService>, FlowyError> {
     if let Some(user_service) = self
       .cache_user_service
       .read()

frontend/rust-lib/flowy-server/src/lib.rs

@@ -6,7 +6,7 @@ use parking_lot::RwLock;
 use flowy_database_deps::cloud::DatabaseCloudService;
 use flowy_document_deps::cloud::DocumentCloudService;
 use flowy_folder_deps::cloud::FolderCloudService;
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 
 pub mod local_server;
 mod request;
@@ -33,12 +33,63 @@ where
   }
 }
 
+/// `AppFlowyServer` trait defines a collection of services that offer cloud-based interactions
+/// and functionalities in AppFlowy. The methods provided ensure efficient, asynchronous operations
+/// for managing and accessing user data, folders, collaborative objects, and documents in a cloud environment.
 pub trait AppFlowyServer: Send + Sync + 'static {
+  /// Enables or disables server sync.
+  ///
+  /// # Arguments
+  ///
+  /// * `_enable` - A boolean to toggle the server synchronization.
   fn set_enable_sync(&self, _enable: bool) {}
-  fn user_service(&self) -> Arc<dyn UserService>;
+
+  /// Provides access to cloud-based user management functionalities. This includes operations
+  /// such as user registration, authentication, profile management, and handling of user workspaces.
+  /// The interface also offers methods for managing collaborative objects, subscribing to user updates,
+  /// and receiving real-time events.
+  ///
+  /// # Returns
+  ///
+  /// An `Arc` wrapping the `UserCloudService` interface.
+  fn user_service(&self) -> Arc<dyn UserCloudService>;
+
+  /// Provides a service for managing workspaces and folders in a cloud environment. This includes
+  /// functionalities to create workspaces, and fetch data, snapshots, and updates related to specific folders.
+  ///
+  /// # Returns
+  ///
+  /// An `Arc` wrapping the `FolderCloudService` interface.
   fn folder_service(&self) -> Arc<dyn FolderCloudService>;
+
+  /// Offers a set of operations for interacting with collaborative objects within a cloud database.
+  /// This includes functionalities such as retrieval of updates for specific objects, batch fetching,
+  /// and obtaining snapshots.
+  ///
+  /// # Returns
+  ///
+  /// An `Arc` wrapping the `DatabaseCloudService` interface.
   fn database_service(&self) -> Arc<dyn DatabaseCloudService>;
+
+  /// Facilitates cloud-based document management. This service offers operations for updating documents,
+  /// fetching snapshots, and accessing primary document data in an asynchronous manner.
+  ///
+  /// # Returns
+  ///
+  /// An `Arc` wrapping the `DocumentCloudService` interface.
   fn document_service(&self) -> Arc<dyn DocumentCloudService>;
+
+  /// Manages collaborative objects within a remote storage system. This includes operations such as
+  /// checking storage status, retrieving updates and snapshots, and dispatching updates. The service
+  /// also provides subscription capabilities for real-time updates.
+  ///
+  /// # Arguments
+  ///
+  /// * `collab_object` - A reference to the collaborative object.
+  ///
+  /// # Returns
+  ///
+  /// An `Option` that might contain an `Arc` wrapping the `RemoteCollabStorage` interface.
   fn collab_storage(&self, collab_object: &CollabObject) -> Option<Arc<dyn RemoteCollabStorage>>;
 }
 

frontend/rust-lib/flowy-server/src/local_server/impls/user.rs

@@ -5,7 +5,7 @@ use collab_plugins::cloud_storage::CollabObject;
 use lazy_static::lazy_static;
 use parking_lot::Mutex;
 
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 use flowy_user_deps::entities::*;
 use flowy_user_deps::DEFAULT_USER_NAME;
 use lib_infra::box_any::BoxAny;
@@ -23,7 +23,7 @@ pub(crate) struct LocalServerUserAuthServiceImpl {
   pub db: Arc<dyn LocalServerDB>,
 }
 
-impl UserService for LocalServerUserAuthServiceImpl {
+impl UserCloudService for LocalServerUserAuthServiceImpl {
   fn sign_up(&self, params: BoxAny) -> FutureResult<SignUpResponse, Error> {
     FutureResult::new(async move {
       let params = params.unbox_or_error::<SignUpParams>()?;

frontend/rust-lib/flowy-server/src/local_server/server.rs

@@ -11,7 +11,7 @@ use flowy_folder_deps::cloud::FolderCloudService;
 // use flowy_user::services::database::{
 //   get_user_profile, get_user_workspace, open_collab_db, open_user_db,
 // };
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 use flowy_user_deps::entities::*;
 
 use crate::local_server::impls::{
@@ -48,7 +48,7 @@ impl LocalServer {
 }
 
 impl AppFlowyServer for LocalServer {
-  fn user_service(&self) -> Arc<dyn UserService> {
+  fn user_service(&self) -> Arc<dyn UserCloudService> {
     Arc::new(LocalServerUserAuthServiceImpl {
       db: self.local_db.clone(),
     })

frontend/rust-lib/flowy-server/src/self_host/impls/user.rs

@@ -2,7 +2,7 @@ use anyhow::Error;
 use collab_plugins::cloud_storage::CollabObject;
 
 use flowy_error::{ErrorCode, FlowyError};
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 use flowy_user_deps::entities::*;
 use lib_infra::box_any::BoxAny;
 use lib_infra::future::FutureResult;
@@ -20,7 +20,7 @@ impl SelfHostedUserAuthServiceImpl {
   }
 }
 
-impl UserService for SelfHostedUserAuthServiceImpl {
+impl UserCloudService for SelfHostedUserAuthServiceImpl {
   fn sign_up(&self, params: BoxAny) -> FutureResult<SignUpResponse, Error> {
     let url = self.config.sign_up_url();
     FutureResult::new(async move {

frontend/rust-lib/flowy-server/src/self_host/server.rs

@@ -5,7 +5,7 @@ use collab_plugins::cloud_storage::{CollabObject, RemoteCollabStorage};
 use flowy_database_deps::cloud::DatabaseCloudService;
 use flowy_document_deps::cloud::DocumentCloudService;
 use flowy_folder_deps::cloud::FolderCloudService;
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 
 use crate::self_host::configuration::SelfHostedConfiguration;
 use crate::self_host::impls::{
@@ -25,7 +25,7 @@ impl SelfHostServer {
 }
 
 impl AppFlowyServer for SelfHostServer {
-  fn user_service(&self) -> Arc<dyn UserService> {
+  fn user_service(&self) -> Arc<dyn UserCloudService> {
     Arc::new(SelfHostedUserAuthServiceImpl::new(self.config.clone()))
   }
 

frontend/rust-lib/flowy-server/src/supabase/api/user.rs

@@ -52,7 +52,7 @@ impl<T> SupabaseUserServiceImpl<T> {
   }
 }
 
-impl<T> UserService for SupabaseUserServiceImpl<T>
+impl<T> UserCloudService for SupabaseUserServiceImpl<T>
 where
   T: SupabaseServerService,
 {

frontend/rust-lib/flowy-server/src/supabase/server.rs

@@ -8,7 +8,7 @@ use flowy_database_deps::cloud::DatabaseCloudService;
 use flowy_document_deps::cloud::DocumentCloudService;
 use flowy_folder_deps::cloud::FolderCloudService;
 use flowy_server_config::supabase_config::SupabaseConfiguration;
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 
 use crate::supabase::api::{
   RESTfulPostgresServer, RealtimeCollabUpdateHandler, RealtimeEventHandler, RealtimeUserHandler,
@@ -108,7 +108,7 @@ impl AppFlowyServer for SupabaseServer {
     self.set_enable_sync(enable);
   }
 
-  fn user_service(&self) -> Arc<dyn UserService> {
+  fn user_service(&self) -> Arc<dyn UserCloudService> {
     // handle the realtime collab update event.
     let (user_update_tx, _) = tokio::sync::broadcast::channel(100);
 

frontend/rust-lib/flowy-server/tests/supabase_test/util.rs

@@ -15,7 +15,7 @@ use flowy_server::supabase::api::{
 use flowy_server::supabase::define::{USER_DEVICE_ID, USER_EMAIL, USER_UUID};
 use flowy_server::{AppFlowyEncryption, EncryptionImpl};
 use flowy_server_config::supabase_config::SupabaseConfiguration;
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 
 use crate::setup_log;
 
@@ -46,7 +46,7 @@ pub fn database_service() -> Arc<dyn DatabaseCloudService> {
   Arc::new(SupabaseDatabaseServiceImpl::new(server))
 }
 
-pub fn user_auth_service() -> Arc<dyn UserService> {
+pub fn user_auth_service() -> Arc<dyn UserCloudService> {
   let (server, _encryption_impl) = appflowy_server(None);
   Arc::new(SupabaseUserServiceImpl::new(server, vec![], None))
 }

frontend/rust-lib/flowy-test/tests/util.rs

@@ -19,7 +19,7 @@ use flowy_user::entities::{AuthTypePB, UpdateUserProfilePayloadPB, UserCredentia
 use flowy_user::errors::FlowyError;
 use flowy_user::event_map::UserCloudServiceProvider;
 use flowy_user::event_map::UserEvent::*;
-use flowy_user_deps::cloud::UserService;
+use flowy_user_deps::cloud::UserCloudService;
 use flowy_user_deps::entities::AuthType;
 
 pub fn get_supabase_config() -> Option<SupabaseConfiguration> {
@@ -110,7 +110,7 @@ pub fn database_service() -> Arc<dyn DatabaseCloudService> {
   Arc::new(SupabaseDatabaseServiceImpl::new(server))
 }
 
-pub fn user_auth_service() -> Arc<dyn UserService> {
+pub fn user_auth_service() -> Arc<dyn UserCloudService> {
   let (server, _encryption_impl) = appflowy_server(None);
   Arc::new(SupabaseUserServiceImpl::new(server, vec![], None))
 }

frontend/rust-lib/flowy-user-deps/src/cloud.rs

@@ -58,7 +58,7 @@ impl Display for UserCloudConfig {
 
 /// Provide the generic interface for the user cloud service
 /// The user cloud service is responsible for the user authentication and user profile management
-pub trait UserService: Send + Sync {
+pub trait UserCloudService: Send + Sync {
   /// Sign up a new account.
   /// The type of the params is defined the this trait's implementation.
   /// Use the `unbox_or_error` of the [BoxAny] to get the params.

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

@@ -5,7 +5,7 @@ use strum_macros::Display;
 
 use flowy_derive::{Flowy_Event, ProtoBuf_Enum};
 use flowy_error::FlowyResult;
-use flowy_user_deps::cloud::{UserCloudConfig, UserService};
+use flowy_user_deps::cloud::{UserCloudConfig, UserCloudService};
 use flowy_user_deps::entities::*;
 use lib_dispatch::prelude::*;
 use lib_infra::future::{to_fut, Fut};
@@ -106,7 +106,7 @@ pub trait UserCloudServiceProvider: Send + Sync + 'static {
   fn set_encrypt_secret(&self, secret: String);
   fn set_auth_type(&self, auth_type: AuthType);
   fn set_device_id(&self, device_id: &str);
-  fn get_user_service(&self) -> Result<Arc<dyn UserService>, FlowyError>;
+  fn get_user_service(&self) -> Result<Arc<dyn UserCloudService>, FlowyError>;
   fn service_name(&self) -> String;
 }
 
@@ -130,7 +130,7 @@ where
     (**self).set_device_id(device_id)
   }
 
-  fn get_user_service(&self) -> Result<Arc<dyn UserService>, FlowyError> {
+  fn get_user_service(&self) -> Result<Arc<dyn UserCloudService>, FlowyError> {
     (**self).get_user_service()
   }