more docs & clean up

Author: hiroshihorie

lib/src/core/engine.dart

@@ -1,8 +1,7 @@
 import 'dart:async';
 
-import 'package:flutter/foundation.dart';
-
 import 'package:collection/collection.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
 import 'package:meta/meta.dart';
 
@@ -11,6 +10,7 @@ import '../events.dart';
 import '../exceptions.dart';
 import '../extensions.dart';
 import '../internal/events.dart';
+import '../internal/types.dart';
 import '../logger.dart';
 import '../managers/delay.dart';
 import '../managers/event.dart';

lib/src/core/transport.dart

@@ -4,6 +4,7 @@ import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
 
 import '../constants.dart';
 import '../extensions.dart';
+import '../internal/types.dart';
 import '../logger.dart';
 import '../support/disposable.dart';
 import '../types.dart';

lib/src/internal/types.dart

@@ -1,18 +1,32 @@
-
 import 'dart:ui';
 
 import 'package:meta/meta.dart';
 
 @internal
+@immutable
 class RendererVisibility {
   final String rendererId;
   final String trackId;
   final bool visible;
   final Size size;
-  RendererVisibility({
+  const RendererVisibility({
     required this.rendererId,
     required this.trackId,
     required this.visible,
     required this.size,
   });
-}
+}
+
+@internal
+@immutable
+class RTCOfferOptions {
+  final bool iceRestart;
+
+  const RTCOfferOptions({
+    this.iceRestart = false,
+  });
+
+  Map<String, dynamic> toMap() => <String, dynamic>{
+        if (iceRestart) 'iceRestart': true,
+      };
+}

lib/src/managers/event.dart

@@ -86,22 +86,6 @@ abstract class EventsListenable<T> extends Disposable {
     }
   }
 
-  // @override
-  // @mustCallSuper
-  // Future<bool> dispose() async {
-  //   // mark as disposed
-  //   final didDispose = await super.dispose();
-  //   if (didDispose && _listeners.isNotEmpty) {
-  //     // Stop listening to all events
-  //     logger.fine('${objectId} dispose() cancelling ${_listeners.length} event(s)');
-  //     for (final listener in _listeners) {
-  //       await listener.cancel();
-  //     }
-  //   }
-
-  //   return didDispose;
-  // }
-
   // listens to all events, guaranteed to be cancelled on dispose
   CancelListenFunc listen(FutureOr<void> Function(T) onEvent) {
     //

lib/src/participant/local.dart

@@ -1,5 +1,6 @@
 import 'package:flutter/foundation.dart';
 import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
+import 'package:meta/meta.dart';
 
 import '../core/room.dart';
 import '../events.dart';
@@ -19,7 +20,7 @@ import 'participant.dart';
 /// Represents the current participant in the room. Instance of [LocalParticipant] is automatically
 /// created after successfully connecting to a [Room] and will be accessible from [Room.localParticipant].
 class LocalParticipant extends Participant<LocalTrackPublication> {
-  //
+  @internal
   LocalParticipant({
     required Room room,
     required lk_models.ParticipantInfo info,
@@ -240,10 +241,6 @@ class LocalParticipant extends Participant<LocalTrackPublication> {
     await room.engine.sendDataPacket(packet);
   }
 
-  @override
-  List<LocalTrackPublication> get subscribedTracks =>
-      super.subscribedTracks.cast<LocalTrackPublication>().toList();
-
   /// A convenience property to get all video tracks.
   @override
   List<LocalTrackPublication<LocalVideoTrack>> get videoTracks =>

lib/src/participant/participant.dart

@@ -80,21 +80,16 @@ abstract class Participant<T extends TrackPublication>
   /// Connection quality between the [Participant] and the Server.
   ConnectionQuality get connectionQuality => _connectionQuality;
 
-  /// [Track]s that this [Participant] is subscribed to.
-  List<T> get subscribedTracks =>
-      trackPublications.values.where((e) => e.subscribed).toList();
-
   // Must be implemented by child class.
   List<T> get videoTracks;
 
   // Must be implemented by child class.
   List<T> get audioTracks;
 
-  /// for internal use
-  /// {@nodoc}
   @internal
   bool get hasInfo => _participantInfo != null;
 
+  @internal
   Participant({
     required this.room,
     required this.sid,

lib/src/participant/remote.dart

@@ -17,22 +17,7 @@ import 'participant.dart';
 
 /// Represents other participant in the [Room].
 class RemoteParticipant extends Participant<RemoteTrackPublication> {
-  @override
-  List<RemoteTrackPublication> get subscribedTracks =>
-      super.subscribedTracks.cast<RemoteTrackPublication>().toList();
-
-  @override
-  List<RemoteTrackPublication<RemoteVideoTrack>> get videoTracks =>
-      trackPublications.values
-          .whereType<RemoteTrackPublication<RemoteVideoTrack>>()
-          .toList();
-
-  @override
-  List<RemoteTrackPublication<RemoteAudioTrack>> get audioTracks =>
-      trackPublications.values
-          .whereType<RemoteTrackPublication<RemoteAudioTrack>>()
-          .toList();
-
+  @internal
   RemoteParticipant({
     required Room room,
     required String sid,
@@ -43,6 +28,7 @@ class RemoteParticipant extends Participant<RemoteTrackPublication> {
           identity: identity,
         );
 
+  @internal
   RemoteParticipant.fromInfo({
     required Room room,
     required lk_models.ParticipantInfo info,
@@ -54,6 +40,25 @@ class RemoteParticipant extends Participant<RemoteTrackPublication> {
     updateFromInfo(info);
   }
 
+  /// A convenience property to get all video tracks.
+  @override
+  List<RemoteTrackPublication<RemoteVideoTrack>> get videoTracks =>
+      trackPublications.values
+          .whereType<RemoteTrackPublication<RemoteVideoTrack>>()
+          .toList();
+
+  /// A convenience property to get all audio tracks.
+  @override
+  List<RemoteTrackPublication<RemoteAudioTrack>> get audioTracks =>
+      trackPublications.values
+          .whereType<RemoteTrackPublication<RemoteAudioTrack>>()
+          .toList();
+
+  List<RemoteTrackPublication> get subscribedTracks => trackPublications.values
+      .where((e) => e.subscribed)
+      .cast<RemoteTrackPublication>()
+      .toList();
+
   RemoteTrackPublication? getTrackPublication(String sid) {
     final pub = trackPublications[sid];
     if (pub is RemoteTrackPublication) return pub;

lib/src/publication/local.dart

@@ -3,7 +3,9 @@ import '../proto/livekit_models.pb.dart' as lk_models;
 import '../track/local/local.dart';
 import 'track_publication.dart';
 
+/// A [TrackPublication] which belongs to the [LocalParticipant].
 class LocalTrackPublication<T extends LocalTrack> extends TrackPublication<T> {
+  /// The [LocalParticipant] this instance belongs to.
   @override
   final LocalParticipant participant;
 

lib/src/types.dart

@@ -3,29 +3,35 @@ import 'dart:math' as math;
 import 'package:flutter/material.dart';
 
 import 'extensions.dart';
+import 'participant/participant.dart';
 
 typedef CancelListenFunc = Function();
 
+/// Protocol version to use when connecting to server.
+/// Usually it's not recommended to change this.
 enum ProtocolVersion {
   v2,
   v3,
   v4,
   v5,
 }
 
+/// Connection state type used throughout the SDK.
 enum ConnectionState {
   disconnected,
   connected,
   reconnecting,
 }
 
+/// Connection quality between the [Participant] and server.
 enum ConnectionQuality {
   unknown,
   poor,
   good,
   excellent,
 }
 
+/// Reliability used for publishing data through data channel.
 enum Reliability {
   reliable,
   lossy,
@@ -39,6 +45,8 @@ enum TrackSource {
   screenShareAudio,
 }
 
+/// The state of track data stream.
+/// This is controlled by server to optimize bandwidth.
 enum StreamState {
   paused,
   active,
@@ -49,31 +57,21 @@ enum CloseReason {
   // ...
 }
 
+/// The reason why a track failed to publish.
 enum TrackSubscribeFailReason {
   invalidServerResponse,
   notTrackMetadataFound,
   unsupportedTrackType,
   // ...
 }
 
+/// The iceTransportPolicy used for [RTCConfiguration].
+/// See https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection
 enum RTCIceTransportPolicy {
   all,
   relay,
 }
 
-@immutable
-class RTCOfferOptions {
-  final bool iceRestart;
-
-  const RTCOfferOptions({
-    this.iceRestart = false,
-  });
-
-  Map<String, dynamic> toMap() => <String, dynamic>{
-        if (iceRestart) 'iceRestart': true,
-      };
-}
-
 @immutable
 class RTCConfiguration {
   final int? iceCandidatePoolSize;
@@ -135,6 +133,7 @@ class RTCIceServer {
       };
 }
 
+/// A simple class that represents dimensions of video.
 @immutable
 class VideoDimensions {
   final int width;
@@ -146,7 +145,7 @@ class VideoDimensions {
   );
 
   @override
-  String toString() => 'VideoDimensions(${width}×${height})';
+  String toString() => '${runtimeType}(${width}x${height})';
 
   /// Returns the larger value
   int max() => math.max(width, height);