From 9bef8452d3a9187f8391b89ffabca76f40c256a8 Mon Sep 17 00:00:00 2001 From: Krille Fear Date: Tue, 16 Mar 2021 12:32:21 +0000 Subject: [PATCH] docs: Clean up dart documentations Changing to `code` blocks where it cant be resolved to [stuff] things. --- .gitlab-ci.yml | 25 ++++++++----------- lib/encryption.dart | 1 + lib/encryption/ssss.dart | 2 +- lib/famedlysdk.dart | 1 + lib/src/client.dart | 21 ++++++++-------- lib/src/event.dart | 2 +- lib/src/room.dart | 10 ++++---- lib/src/timeline.dart | 6 ++--- lib/src/utils/commands_extension.dart | 6 ++--- lib/src/utils/matrix_id_string_extension.dart | 8 +++--- lib/src/utils/room_update.dart | 4 +-- lib/src/utils/uri_extension.dart | 8 +++--- prepare.sh => scripts/prepare.sh | 0 test.sh => scripts/test.sh | 0 test_driver.sh => scripts/test_driver.sh | 0 15 files changed, 47 insertions(+), 47 deletions(-) rename prepare.sh => scripts/prepare.sh (100%) rename test.sh => scripts/test.sh (100%) rename test_driver.sh => scripts/test_driver.sh (100%) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 756b5c96..fd20fab3 100644 --- a/.gitlab-ci.yml +++ b/.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: diff --git a/lib/encryption.dart b/lib/encryption.dart index 89c30c68..f534f836 100644 --- a/lib/encryption.dart +++ b/lib/encryption.dart @@ -16,6 +16,7 @@ * along with this program. If not, see . */ +/// Matrix SDK encryption specific extension library encryption; export 'encryption/encryption.dart'; diff --git a/lib/encryption/ssss.dart b/lib/encryption/ssss.dart index 4dfcbf64..a27bf928 100644 --- a/lib/encryption/ssss.dart +++ b/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 createKey([String passphrase]) async { Uint8List privateKey; final content = SecretStorageKeyContent(); diff --git a/lib/famedlysdk.dart b/lib/famedlysdk.dart index 1f7aba74..3b9a3fdb 100644 --- a/lib/famedlysdk.dart +++ b/lib/famedlysdk.dart @@ -16,6 +16,7 @@ * along with this program. If not, see . */ +/// Matrix SDK written in pure Dart. library famedlysdk; export 'package:matrix_api_lite/matrix_api_lite.dart'; diff --git a/lib/src/client.dart b/lib/src/client.dart index bae77cb6..5001b68d 100644 --- a/lib/src/client.dart +++ b/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 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 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 sendToDeviceEncrypted( List 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 sendToDeviceEncryptedChunked( List deviceKeys, String eventType, diff --git a/lib/src/event.dart b/lib/src/event.dart index 7b6d630a..39e834a9 100644 --- a/lib/src/event.dart +++ b/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 redact({String reason, String txid}) => room.redactEvent(eventId, reason: reason, txid: txid); diff --git a/lib/src/room.dart b/lib/src/room.dart index aac4e153..a4d45696 100644 --- a/lib/src/room.dart +++ b/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> 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 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; diff --git a/lib/src/timeline.dart b/lib/src/timeline.dart index c7515d4c..7f568cbb 100644 --- a/lib/src/timeline.dart +++ b/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 events; diff --git a/lib/src/utils/commands_extension.dart b/lib/src/utils/commands_extension.dart index 7e89a620..722fe9d7 100644 --- a/lib/src/utils/commands_extension.dart +++ b/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 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 parseAndRunCommand(Room room, String msg, {Event inReplyTo, String editEventId, String txid}) async { final args = CommandArgs( diff --git a/lib/src/utils/matrix_id_string_extension.dart b/lib/src/utils/matrix_id_string_extension.dart index 281f7060..1c0db5f1 100644 --- a/lib/src/utils/matrix_id_string_extension.dart +++ b/lib/src/utils/matrix_id_string_extension.dart @@ -16,11 +16,11 @@ * along with this program. If not, see . */ +const Set VALID_SIGILS = {'@', '!', '#', '\$', '+'}; + +const int MAX_LENGTH = 255; + extension MatrixIdExtension on String { - static const Set VALID_SIGILS = {'@', '!', '#', '\$', '+'}; - - static const int MAX_LENGTH = 255; - List _getParts() { final s = substring(1); final ix = s.indexOf(':'); diff --git a/lib/src/utils/room_update.dart b/lib/src/utils/room_update.dart index 0281e06b..532fbee8 100644 --- a/lib/src/utils/room_update.dart +++ b/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. diff --git a/lib/src/utils/uri_extension.dart b/lib/src/utils/uri_extension.dart index bf04568c..a0925df5 100644 --- a/lib/src/utils/uri_extension.dart +++ b/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, diff --git a/prepare.sh b/scripts/prepare.sh similarity index 100% rename from prepare.sh rename to scripts/prepare.sh diff --git a/test.sh b/scripts/test.sh similarity index 100% rename from test.sh rename to scripts/test.sh diff --git a/test_driver.sh b/scripts/test_driver.sh similarity index 100% rename from test_driver.sh rename to scripts/test_driver.sh