docs: Clean up dart documentations

Changing to `code` blocks where it cant be resolved to [stuff] things.

.gitlab-ci.yml

@@ -27,11 +27,11 @@ coverage:
     - ln -s /usr/lib/dart/bin/pub /usr/bin/
     - useradd -m test
     - chown -R 'test:' '.'
-    - chmod +x ./prepare.sh
-    - chmod +x ./test.sh
+    - chmod +x ./scripts/prepare.sh
+    - chmod +x ./scripts/test.sh
     - rm -r example
-    - ./prepare.sh test
-    - ./test.sh test
+    - ./scripts/prepare.sh test
+    - ./scripts/test.sh test
   artifacts:
     paths:
       - coverage/
@@ -50,9 +50,6 @@ coverage_without_olm:
     - apt update
     - apt install -y dart
     - ln -s /usr/lib/dart/bin/pub /usr/bin/
-    - useradd -m test
-    - chown -R 'test:' '.'
-    - chmod +x ./test.sh
     - pub get
     - pub run test
 
@@ -72,11 +69,11 @@ e2ee_test:
     - ln -s /usr/lib/dart/bin/pub /usr/bin/
     - useradd -m test
     - chown -R 'test:' '.'
-    - chmod +x ./prepare.sh
-    - chmod +x ./test_driver.sh
+    - chmod +x ./scripts/prepare.sh
+    - chmod +x ./scripts/test_driver.sh
     - printf "abstract class TestUser {\n  static const String homeserver = '$TEST_HOMESERVER';\n  static const String username = '$TEST_USER1';\n  static const String username2 = '$TEST_USER2';\n  static const String password = '$TEST_USER_PASSWORD';\n}" > ./test_driver/test_config.dart
-    - su -c ./prepare.sh test
-    - su -c ./test_driver.sh test
+    - su -c ./scripts/prepare.sh test
+    - su -c ./scripts/test_driver.sh test
   timeout: 16m
   resource_group: e2ee_test
 
@@ -94,14 +91,14 @@ build_api_doc:
   tags:
     - docker
   stage: builddocs
-  image: cirrusci/flutter
+  image: registry.gitlab.com/famedly/containers/flutter-dockerimages:stable
   script:
+    - flutter pub global activate dartdoc
+    - export PATH="$PATH":"/opt/flutter/flutter/.pub-cache/bin"
     - dartdoc --exclude "dart:async,dart:collection,dart:convert,dart:core,dart:developer,dart:io,dart:isolate,dart:math,dart:typed_data,dart:ui"
   artifacts:
     paths:
       - doc/api/
-  rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 
 build_doc:
   tags:

lib/encryption.dart

@@ -16,6 +16,7 @@
  *   along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+/// Matrix SDK encryption specific extension
 library encryption;
 
 export 'encryption/encryption.dart';

lib/encryption/ssss.dart

@@ -200,7 +200,7 @@ class SSSS {
       getKey(keyId)?.algorithm == AlgorithmTypes.secretStorageV1AesHmcSha2;
 
   /// Creates a new secret storage key, optional encrypts it with [passphrase]
-  /// and stores it in the user's [accountData].
+  /// and stores it in the user's `accountData`.
   Future<OpenSSSS> createKey([String passphrase]) async {
     Uint8List privateKey;
     final content = SecretStorageKeyContent();

lib/famedlysdk.dart

@@ -16,6 +16,7 @@
  *   along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+/// Matrix SDK written in pure Dart.
 library famedlysdk;
 
 export 'package:matrix_api_lite/matrix_api_lite.dart';

lib/src/client.dart

@@ -311,8 +311,8 @@ class Client extends MatrixApi {
 
   /// Checks the supported versions of the Matrix protocol and the supported
   /// login types. Throws an exception if the server is not compatible with the
-  /// client and sets [homeserver] to [serverUrl] if it is. Supports the types [Uri]
-  /// and [String].
+  /// client and sets [homeserver] to [homeserverUrl] if it is. Supports the
+  /// types `Uri` and `String`.
   Future<WellKnownInformation> checkHomeserver(dynamic homeserverUrl,
       {bool checkWellKnown = true}) async {
     try {
@@ -1452,7 +1452,7 @@ sort order of ${prevState.sortOrder}. This should never happen...''');
 
   bool _sortLock = false;
 
-  /// If [true] then unread rooms are pinned at the top of the room list.
+  /// If `true` then unread rooms are pinned at the top of the room list.
   bool pinUnreadRooms;
 
   /// The compare function how the rooms should be sorted internally. By default
@@ -1731,9 +1731,9 @@ sort order of ${prevState.sortOrder}. This should never happen...''');
     }
   }
 
-  /// Sends a raw to_device event with a [eventType], a [txnId] and a content [data].
-  /// Before sending, it tries to re-send potentially queued to_device events and adds
-  /// the current one to the queue, should it fail.
+  /// Sends a raw to_device event with a [eventType], a [txnId] and a content
+  /// [messages]. Before sending, it tries to re-send potentially queued
+  /// to_device events and adds the current one to the queue, should it fail.
   @override
   Future<void> sendToDevice(
     String eventType,
@@ -1776,7 +1776,7 @@ sort order of ${prevState.sortOrder}. This should never happen...''');
     return;
   }
 
-  /// Sends an encrypted [message] of this [type] to these [deviceKeys].
+  /// Sends an encrypted [message] of this [eventType] to these [deviceKeys].
   Future<void> sendToDeviceEncrypted(
     List<DeviceKeys> deviceKeys,
     String eventType,
@@ -1804,9 +1804,10 @@ sort order of ${prevState.sortOrder}. This should never happen...''');
         eventType, messageId ?? generateUniqueTransactionId(), data);
   }
 
-  /// Sends an encrypted [message] of this [type] to these [deviceKeys]. This request happens
-  /// partly in the background and partly in the foreground. It automatically chunks sending
-  /// to device keys based on activity
+  /// Sends an encrypted [message] of this [eventType] to these [deviceKeys].
+  /// This request happens partly in the background and partly in the
+  /// foreground. It automatically chunks sending to device keys based on
+  /// activity.
   Future<void> sendToDeviceEncryptedChunked(
     List<DeviceKeys> deviceKeys,
     String eventType,

lib/src/event.dart

@@ -346,7 +346,7 @@ class Event extends MatrixEvent {
   /// Whether the client is allowed to redact this event.
   bool get canRedact => senderId == room.client.userID || room.canRedact;
 
-  /// Redacts this event. Returns [ErrorResponse] on error.
+  /// Redacts this event. Throws `ErrorResponse` on error.
   Future<dynamic> redact({String reason, String txid}) =>
       room.redactEvent(eventId, reason: reason, txid: txid);
 

lib/src/room.dart

@@ -69,9 +69,9 @@ class Room {
   /// The number of users with membership of invite.
   int mInvitedMemberCount;
 
-  /// The room states are a key value store of the key ([type],[state_key]) => State(event).
-  /// In a lot of cases the [state_key] might be an empty string. You **should** use the
-  /// methods [getState] and [setState] to interact with the room states.
+  /// The room states are a key value store of the key (`type`,`state_key`) => State(event).
+  /// In a lot of cases the `state_key` might be an empty string. You **should** use the
+  /// methods `getState()` and `setState()` to interact with the room states.
   Map<String, Map<String, Event>> states = {};
 
   /// Key-Value store for ephemerals.
@@ -1531,7 +1531,7 @@ class Room {
     return resp;
   }
 
-  /// Redacts this event. Returns [ErrorResponse] on error.
+  /// Redacts this event. Throws `ErrorResponse` on error.
   Future<String> redactEvent(String eventId,
       {String reason, String txid}) async {
     // Create new transaction id
@@ -1808,7 +1808,7 @@ class Room {
   }
 
   /// Whether this is an extinct room which has been archived in favor of a new
-  /// room which replaces this. Use [getLegacyRoomInformations] to get more
+  /// room which replaces this. Use `getLegacyRoomInformations()` to get more
   /// informations about it if this is true.
   bool get isExtinct => getState(EventTypes.RoomTombstone) != null;
 

lib/src/timeline.dart

@@ -27,9 +27,9 @@ import 'utils/room_update.dart';
 typedef onTimelineUpdateCallback = void Function();
 typedef onTimelineInsertCallback = void Function(int insertID);
 
-/// Represents the timeline of a room. The callbacks [onUpdate], [onDelete],
-/// [onInsert] and [onResort] will be triggered automatically. The initial
-/// event list will be retreived when created by the [room.getTimeline] method.
+/// Represents the timeline of a room. The callback [onUpdate] will be triggered
+/// automatically. The initial
+/// event list will be retreived when created by the `room.getTimeline()` method.
 class Timeline {
   final Room room;
   final List<Event> events;

lib/src/utils/commands_extension.dart

@@ -21,15 +21,15 @@ import 'dart:async';
 import '../../famedlysdk.dart';
 
 extension CommandsClientExtension on Client {
-  /// Add a command to the command handler. [command] is its name, and [callback] is the
+  /// Add a command to the command handler. `command` is its name, and `callback` is the
   /// callback to invoke
   void addCommand(
       String command, FutureOr<String> Function(CommandArgs) callback) {
     commands[command.toLowerCase()] = callback;
   }
 
-  /// Parse and execute a string, [msg] is the input. Optionally [inReplyTo] is the event being
-  /// replied to and [editEventId] is the eventId of the event being replied to
+  /// Parse and execute a string, `msg` is the input. Optionally `inReplyTo` is the event being
+  /// replied to and `editEventId` is the eventId of the event being replied to
   Future<String> parseAndRunCommand(Room room, String msg,
       {Event inReplyTo, String editEventId, String txid}) async {
     final args = CommandArgs(

lib/src/utils/matrix_id_string_extension.dart

@@ -16,11 +16,11 @@
  *   along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+const Set<String> VALID_SIGILS = {'@', '!', '#', '\$', '+'};
+
+const int MAX_LENGTH = 255;
+
 extension MatrixIdExtension on String {
-  static const Set<String> VALID_SIGILS = {'@', '!', '#', '\$', '+'};
-
-  static const int MAX_LENGTH = 255;
-
   List<String> _getParts() {
     final s = substring(1);
     final ix = s.indexOf(':');

lib/src/utils/room_update.dart

@@ -34,8 +34,8 @@ class RoomUpdate {
   // The number of unread highlighted notifications.
   final num highlight_count;
 
-  /// If there are too much new messages, the [homeserver] will only send the
-  /// last X (default is 10) messages and set the [limitedTimelinbe] flag to true.
+  /// If there are too much new messages, the `homeserver` will only send the
+  /// last X (default is 10) messages and set the `limitedTimeline` flag to true.
   final bool limitedTimeline;
 
   /// Represents the current position of the client in the room history.

lib/src/utils/uri_extension.dart

@@ -28,10 +28,10 @@ extension MxcUriExtension on Uri {
           : ''
       : toString();
 
-  /// Returns a scaled thumbnail link to this content with the given [width] and
-  /// [height]. [method] can be [ThumbnailMethod.crop] or
-  /// [ThumbnailMethod.scale] and defaults to [ThumbnailMethod.scale].
-  /// If [animated] (default false) is set to true, an animated thumbnail is requested
+  /// Returns a scaled thumbnail link to this content with the given `width` and
+  /// `height`. `method` can be `ThumbnailMethod.crop` or
+  /// `ThumbnailMethod.scale` and defaults to `ThumbnailMethod.scale`.
+  /// If `animated` (default false) is set to true, an animated thumbnail is requested
   /// as per MSC2705. Thumbnails only animate if the media repository supports that.
   String getThumbnail(Client matrix,
       {num width,