From 6061771053620f5bfe00e4383511ed6f3ac88455 Mon Sep 17 00:00:00 2001 From: Ben Hagen Date: Thu, 5 Dec 2019 20:02:06 +0100 Subject: [PATCH 1/4] Document public API. --- .../lib/video_player_platform_interface.dart | 57 ++++++++++++++++++- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart b/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart index d8aa26d6ee46..7597514eaf4b 100644 --- a/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart +++ b/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart @@ -119,7 +119,10 @@ abstract class VideoPlayerPlatform { void _verifyProvidesDefaultImplementations() {} } +/// Description of the data source used to create an instance of +/// the video player. class DataSource { + /// Constructs an instance of [DataSource]. DataSource({ @required this.sourceType, this.uri, @@ -128,16 +131,34 @@ class DataSource { this.package, }); + /// The way in which the video was originally loaded. + /// + /// This has nothing to do with the video's file type. It's just the place + /// from which the video is fetched from. final DataSourceType sourceType; + + /// The URI to the video file. + /// + /// This will be in different formats depending on the [DataSourceType] of + /// the original video. final String uri; + + /// **Android only**. Will override the platform's generic file format + /// detection with whatever is set here. final VideoFormat formatHint; + + /// The name of the asset. Only set for [DataSourceType.asset] videos. final String asset; + + /// The package that the asset was loaded from. Only set for + /// [DataSourceType.asset] videos. final String package; } -/// The way in which the video was originally loaded. This has nothing to do -/// with the video's file type. It's just the place from which the video is -/// fetched from. +/// The way in which the video was originally loaded. +/// +/// This has nothing to do with the video's file type. It's just the place +/// from which the video is fetched from. enum DataSourceType { /// The video was included in the app's asset files. asset, @@ -164,7 +185,9 @@ enum VideoFormat { other } +/// Event emitted from the platform implementation. class VideoEvent { + /// Creates an instance of [VideoEvent]. VideoEvent({ @required this.eventType, this.duration, @@ -172,9 +195,22 @@ class VideoEvent { this.buffered, }); + /// The type of the event. final VideoEventType eventType; + + /// Duration of the video. + /// + /// Only used if [eventType] is [VideoEventType.initialized]. final Duration duration; + + /// Size of the video. + /// + /// Only used if [eventType] is [VideoEventType.initialized]. final Size size; + + /// Buffered parts of the video. + /// + /// Only used if [eventType] is [VideoEventType.bufferingUpdate]. final List buffered; @override @@ -196,12 +232,27 @@ class VideoEvent { buffered.hashCode; } +/// Type of the event. +/// +/// Emitted by the platform implementation when the video is initialized or +/// completed or to communicate buffering events. enum VideoEventType { + /// The video has been initialized. initialized, + + /// The playback has ended. completed, + + /// Updated information on the buffering state. bufferingUpdate, + + /// The video started to buffer. bufferingStart, + + /// The video stopped to buffer. bufferingEnd, + + /// An unknown event has been received. unknown, } From 4b65509bec73078d3c800d5adec928e83943cdb6 Mon Sep 17 00:00:00 2001 From: Ben Hagen Date: Thu, 5 Dec 2019 20:06:40 +0100 Subject: [PATCH 2/4] Update version and changelog. --- .../video_player/video_player_platform_interface/CHANGELOG.md | 4 ++++ .../video_player/video_player_platform_interface/pubspec.yaml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/video_player/video_player_platform_interface/CHANGELOG.md b/packages/video_player/video_player_platform_interface/CHANGELOG.md index acaff15f5466..7c77697dfd06 100644 --- a/packages/video_player/video_player_platform_interface/CHANGELOG.md +++ b/packages/video_player/video_player_platform_interface/CHANGELOG.md @@ -1,3 +1,7 @@ +## 1.0.3 + +* Document public API. + ## 1.0.2 * Fix unawaited futures in the tests. diff --git a/packages/video_player/video_player_platform_interface/pubspec.yaml b/packages/video_player/video_player_platform_interface/pubspec.yaml index 38bde72e28fc..1a9454d10fef 100644 --- a/packages/video_player/video_player_platform_interface/pubspec.yaml +++ b/packages/video_player/video_player_platform_interface/pubspec.yaml @@ -4,7 +4,7 @@ author: Flutter Team homepage: https://github.com/flutter/plugins/tree/master/packages/video_player/video_player_platform_interface # NOTE: We strongly prefer non-breaking changes, even at the expense of a # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes -version: 1.0.2 +version: 1.0.3 dependencies: flutter: From 3e319cb5ba6028a0afc604ce6aa093248a190539 Mon Sep 17 00:00:00 2001 From: Ben Hagen Date: Thu, 5 Dec 2019 20:17:15 +0100 Subject: [PATCH 3/4] Remove analysis_options.yaml --- .../analysis_options.yaml | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100644 packages/video_player/video_player_platform_interface/analysis_options.yaml diff --git a/packages/video_player/video_player_platform_interface/analysis_options.yaml b/packages/video_player/video_player_platform_interface/analysis_options.yaml deleted file mode 100644 index 969b55796944..000000000000 --- a/packages/video_player/video_player_platform_interface/analysis_options.yaml +++ /dev/null @@ -1,10 +0,0 @@ -# This is a temporary file to allow us to land a new set of linter rules in a -# series of manageable patches instead of one gigantic PR. It disables some of -# the new lints that are already failing on this plugin, for this plugin. It -# should be deleted and the failing lints addressed as soon as possible. - -include: ../../../analysis_options.yaml - -analyzer: - errors: - public_member_api_docs: ignore From a4071b49e0e1a91cbc48cc6cef901fb1f6cc0fd9 Mon Sep 17 00:00:00 2001 From: Ben Hagen Date: Thu, 5 Dec 2019 20:38:36 +0100 Subject: [PATCH 4/4] Improve constructor documentation --- .../lib/video_player_platform_interface.dart | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart b/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart index 7597514eaf4b..4c1f2b67c4fc 100644 --- a/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart +++ b/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart @@ -123,6 +123,18 @@ abstract class VideoPlayerPlatform { /// the video player. class DataSource { /// Constructs an instance of [DataSource]. + /// + /// The [sourceType] is always required. + /// + /// The [uri] argument takes the form of `'https://example.com/video.mp4'` or + /// `'file://${file.path}'`. + /// + /// The [formatHint] argument can be null. + /// + /// The [asset] argument takes the form of `'assets/video.mp4'`. + /// + /// The [package] argument must be non-null when the asset comes from a + /// package and null otherwise. DataSource({ @required this.sourceType, this.uri, @@ -188,6 +200,11 @@ enum VideoFormat { /// Event emitted from the platform implementation. class VideoEvent { /// Creates an instance of [VideoEvent]. + /// + /// The [eventType] argument is required. + /// + /// Depending on the [eventType], the [duration], [size] and [buffered] + /// arguments can be null. VideoEvent({ @required this.eventType, this.duration,