Merge pull request #1636 from famedly/krille/add-documentation

docs: Add documentation

README.md

@@ -10,65 +10,14 @@ Additionally, OpenSSL (libcrypto) must be provided on native platforms for E2EE.
 
 For flutter apps you can easily import it with the [flutter_olm](https://pub.dev/packages/flutter_olm) and the [flutter_openssl_crypto](https://pub.dev/packages/flutter_openssl_crypto) packages.
 
-## How to use this
+```sh
-
+flutter pub add matrix
-1. Import the sdk
+flutter pub add flutter_olm
-
+flutter pub add flutter_openssl_crypto
-```yaml
-  matrix: <latest-version>
-  # Optional:
-  flutter_olm: <latest-version>
-  flutter_openssl_crypto: <latest-version>
 ```
 
-```dart
+## Get started
-import 'package:matrix/matrix.dart';
-```
 
-2. Create a new client:
+See the API documentation for details:
 
-```dart
+[API documentation](https://pub.dev/documentation/matrix/latest/)
-final client = Client("HappyChat");
-```
-
-The SDK works better with a database. Otherwise it has no persistence. For this you need to provide a databaseBuilder like this:
-
-```dart
-final client = Client(
-  "HappyChat",
-  databaseBuilder: (_) async {
-    final dir = await getApplicationSupportDirectory(); // Recommend path_provider package
-    final db = HiveCollectionsDatabase('matrix_example_chat', dir.path);
-    await db.open();
-    return db;
-  },
-);
-```
-
-3. Connect to a Matrix Homeserver and listen to the streams:
-
-```dart
-client.onLoginStateChanged.stream.listen((bool loginState){ 
-  print("LoginState: ${loginState.toString()}");
-});
-
-client.onEvent.stream.listen((EventUpdate eventUpdate){ 
-  print("New event update!");
-});
-
-client.onRoomUpdate.stream.listen((RoomUpdate eventUpdate){ 
-  print("New room update!");
-});
-
-await client.checkHomeserver("https://yourhomeserver.abc");
-await client.login(
-  identifier: AuthenticationUserIdentifier(user: 'alice'),
-  password: '123456',
-);
-```
-
-4. Send a message to a Room:
-
-```dart
-await client.getRoomById('your_room_id').sendTextEvent('Hello world');
-```

doc/get-started.md

@@ -0,0 +1,75 @@
+Follow these steps to get started with your first Matrix Client.
+
+## Step 1: Add dependencies
+
+In your `pubspec.yaml` file add the following dependencies:
+
+```yaml
+  matrix: <latest-version>
+  # If you plan to use the SDK in a Flutter application on IO:
+  sqflite: <latest-version>
+  # For end to end encryption:
+  flutter_olm: <latest-version>
+  flutter_openssl_crypto: <latest-version>
+```
+
+## Step 2: Create the client
+
+```dart
+final client = Client(
+    '<Your Client Name>',
+    databaseBuilder: (client) => MatrixSdkDatabase(
+        '<Database Name>',
+        database: await openDatabase('<path-to-store-database>'),
+    ),
+);
+```
+
+## Step 3: Login
+
+```dart
+// Connect to a homeserver before login:
+final homeserver = Uri.parse('https://matrix.org');
+await client.checkHomeserver(homeserver);
+
+await client.login(
+    LoginType.password,
+    user: AuthenticationUserIdentifier(user: '<your-username>'),
+    password: '<your-password>',
+);
+```
+
+## Step 4: Create a new room
+
+```dart
+// Start a new DM room or return an existing room with a user
+final roomId = await client.startDirectChat('<user-id>');
+
+// Start a new group chat
+final roomId = await client.createGroupChat(name: '<group-name>');
+```
+
+## Step 5: Send messages
+
+```dart
+// Get a specific room by room ID or iterate over `client.rooms`:
+final room = client.getRoomById('<room-id>');
+// Or get the DM room for a user:
+final dmRoom = client.getDirectChatFromUserId('<user-id>');
+
+// Send a normal text message into the room:
+await room.sendTextEvent('<your-message>');
+```
+
+## Step 6: Receive messages
+
+```dart
+// Load the timeline of a room:
+final timeline = await room.getTimeline(
+    onUpdate: reloadYourGui(),
+    onInsert: (i) => print('New message!'),
+);
+
+// Print all messages in the timeline to the console
+for(final event in timeline.events) print(event.calcLocalizedBodyFallback());
+```

doc/web.md

@@ -0,0 +1,25 @@
+To use end to end encryption in web you have to download the olm javascript/wasm library:
+
+```sh
+#!/bin/sh -ve
+rm -r assets/js/package
+
+OLM_VERSION=$(cat pubspec.yaml | yq .dependencies.flutter_olm)
+DOWNLOAD_PATH="https://github.com/famedly/olm/releases/download/v$OLM_VERSION/olm.zip"
+
+curl -L $DOWNLOAD_PATH > olm.zip
+unzip olm.zip
+rm olm.zip
+```
+
+...and import it in your `index.html`:
+
+```html
+<html>
+    <head>
+        ...
+        <script src="path/to/assets/olm.js"></script>
+    </head>
+    ...
+</html>
+```

lib/src/database/matrix_sdk_database.dart

@@ -36,6 +36,20 @@ import 'package:matrix/src/utils/run_benchmarked.dart';
 import 'package:matrix/src/database/indexeddb_box.dart'
     if (dart.library.io) 'package:matrix/src/database/sqflite_box.dart';
 
+/// Database based on SQlite3 on native and IndexedDB on web. For native you
+/// have to pass a `Database` object, which can be created with the sqflite
+/// package like this:
+/// ```dart
+/// final database = await openDatabase('path/to/your/database');
+/// ```
+///
+/// **WARNING**: For android it seems like that the CursorWindow is too small for
+/// large amounts of data if you are using SQFlite. Consider using a different
+///  package to open the database like
+/// [sqflite_sqlcipher](https://pub.dev/packages/sqflite_sqlcipher) or
+/// [sqflite_common_ffi](https://pub.dev/packages/sqflite_common_ffi).
+/// Learn more at:
+/// https://github.com/famedly/matrix-dart-sdk/issues/1642#issuecomment-1865827227
 class MatrixSdkDatabase extends DatabaseApi {
   static const int version = 7;
   final String name;