From 00b24113c364dedd9102d4093585af75f68079b3 Mon Sep 17 00:00:00 2001 From: Neevash Ramdial Date: Fri, 29 Jan 2021 21:02:31 -0400 Subject: [PATCH] [Core] Update documentation with API links --- .../lib/src/channel_list_core.dart | 9 ++++++--- .../lib/src/channels_bloc.dart | 20 ++++++++++++++++++- .../lib/src/lazy_load_scroll_view.dart | 6 +++--- .../lib/src/message_list_core.dart | 7 +++---- .../lib/src/message_search_bloc.dart | 11 +++++++++- .../lib/src/message_search_list_core.dart | 7 ++++++- .../lib/src/stream_channel.dart | 3 ++- .../lib/src/stream_chat_core.dart | 7 +++++++ .../lib/src/users_bloc.dart | 7 +++++++ 9 files changed, 63 insertions(+), 14 deletions(-) diff --git a/packages/stream_chat_flutter_core/lib/src/channel_list_core.dart b/packages/stream_chat_flutter_core/lib/src/channel_list_core.dart index 7a9e7e41..393c3686 100644 --- a/packages/stream_chat_flutter_core/lib/src/channel_list_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/channel_list_core.dart @@ -257,11 +257,14 @@ class _ChannelListCoreState extends State } } -/// Controller used for paginating data in [ChannelListCore] +/// Controller used for loading more data and controlling pagination in [ChannelListCore]. class ChannelListController { - /// Call this function to reload data + /// This function calls Stream's servers to load a list of channels. If there is existing data, + /// calling this function causes a reload. VoidCallback loadData; - /// Call this function to load further data + /// This function is used to load another page of data. Note, [loadData] should be + /// used to populate the initial page of data. Calling [paginateData] performs a query + /// to load subsequent pages. VoidCallback paginateData; } diff --git a/packages/stream_chat_flutter_core/lib/src/channels_bloc.dart b/packages/stream_chat_flutter_core/lib/src/channels_bloc.dart index 2eef0f8a..1c30ad65 100644 --- a/packages/stream_chat_flutter_core/lib/src/channels_bloc.dart +++ b/packages/stream_chat_flutter_core/lib/src/channels_bloc.dart @@ -3,10 +3,28 @@ import 'dart:async'; import 'package:flutter/material.dart'; import 'package:rxdart/rxdart.dart'; import 'package:stream_chat/stream_chat.dart'; +import 'package:stream_chat_flutter_core/src/channel_list_core.dart'; import 'package:stream_chat_flutter_core/src/stream_chat_core.dart'; /// Widget dedicated to the management of a channel list with pagination +/// [ChannelsBloc] is used together with [ChannelListCore] to manage a list of +/// [Channel]s with pagination, re-ordering, querying and other operations +/// associated with [Channel]s. +/// +/// [ChannelsBloc] can be access at anytime by using the static [of] method +/// using Flutter's [BuildContext]. +/// +/// API docs: https://getstream.io/chat/docs/flutter-dart/query_channels/ class ChannelsBloc extends StatefulWidget { + /// Creates a new [ChannelsBloc]. The parameter [child] must be supplied and not null. + const ChannelsBloc({ + Key key, + @required this.child, + this.lockChannelsOrder = false, + this.channelsComparator, + this.shouldAddChannel, + }) : super(key: key); + /// The widget child final Widget child; @@ -45,7 +63,7 @@ class ChannelsBloc extends StatefulWidget { } } -/// The current state of the [ChannelsBloc] +/// The current state of the [ChannelsBloc]. class ChannelsBlocState extends State with AutomaticKeepAliveClientMixin { @override diff --git a/packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart b/packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart index bc1f4d1b..0e118420 100644 --- a/packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart +++ b/packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart @@ -3,8 +3,8 @@ import 'package:flutter/widgets.dart'; enum _LoadingStatus { LOADING, STABLE } -/// A widget that wraps a [Widget] and will trigger [onEndOfPage]/[onStartOfPage] when it -/// reaches the bottom/start of the list +/// Wrapper around a [Scrollable] which triggers [onEndOfPage]/[onStartOfPage] the Scrollable +/// reaches to the start or end of the view extent. class LazyLoadScrollView extends StatefulWidget { /// The [Widget] that this widget watches for changes on final Widget child; @@ -27,7 +27,7 @@ class LazyLoadScrollView extends StatefulWidget { /// The offset to take into account when triggering [onEndOfPage]/[onStartOfPage] in pixels final double scrollOffset; - /// Used to determine if loading of new data has finished. You should use set this if you aren't using a FutureBuilder or StreamBuilder + /// Used to determine if loading of new data has finished. You should use set this if you aren't using a [FutureBuilder] or [StreamBuilder]. final bool isLoading; /// Initiates a LazyLoadScrollView widget diff --git a/packages/stream_chat_flutter_core/lib/src/message_list_core.dart b/packages/stream_chat_flutter_core/lib/src/message_list_core.dart index b8d5c8da..5856575c 100644 --- a/packages/stream_chat_flutter_core/lib/src/message_list_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/message_list_core.dart @@ -53,10 +53,8 @@ import 'stream_channel.dart'; /// Make sure to have a [StreamChannel] ancestor in order to provide the information about the channels. /// The widget uses a [ListView.custom] to render the list of channels. /// -/// The widget components render the ui based on the first ancestor of type [StreamChatTheme]. -/// Modify it to change the widget appearance. class MessageListCore extends StatefulWidget { - /// Instantiate a new MessageListView + /// Instantiate a new [MessageListView] MessageListCore({ Key key, this.showScrollToBottom = true, @@ -89,7 +87,8 @@ class MessageListCore extends StatefulWidget { /// If true will show a scroll to bottom message when there are new messages and the scroll offset is not zero final bool showScrollToBottom; - /// Parent message in case of a thread + /// If the current message belongs to a `thread`, this property represents the + /// first message or the parent of the conversation. final Message parentMessage; @override diff --git a/packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart b/packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart index ca6a983d..615f5374 100644 --- a/packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart +++ b/packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart @@ -4,7 +4,13 @@ import 'package:stream_chat/stream_chat.dart'; import 'stream_chat_core.dart'; -/// Widget dedicated to the management of a message list with pagination +/// [MessageSearchBloc] is used to manage a list of messages with pagination. +/// This class can be used to load messages, perform queries, etc. +/// +/// [MessageSearchBloc] can be access at anytime by using the static [of] method +/// using Flutter's [BuildContext]. +/// +// API docs: https://getstream.io/chat/docs/flutter-dart/send_message/ class MessageSearchBloc extends StatefulWidget { /// The widget child final Widget child; @@ -15,6 +21,9 @@ class MessageSearchBloc extends StatefulWidget { @required this.child, }) : super(key: key); + /// The widget child + final Widget child; + @override MessageSearchBlocState createState() => MessageSearchBlocState(); diff --git a/packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart b/packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart index 1eefc3a0..26ee58c1 100644 --- a/packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart @@ -32,7 +32,12 @@ import 'message_search_bloc.dart'; /// The widget uses a [ListView.separated] to render the list of messages. /// class MessageSearchListCore extends StatefulWidget { - /// Instantiate a new MessageSearchListView + /// Instantiate a new [MessageSearchListView]. + /// The following parameters must be supplied and not null: + /// * [emptyBuilder] + /// * [errorBuilder] + /// * [loadingBuilder] + /// * [childBuilder] const MessageSearchListCore({ Key key, @required this.emptyBuilder, diff --git a/packages/stream_chat_flutter_core/lib/src/stream_channel.dart b/packages/stream_chat_flutter_core/lib/src/stream_channel.dart index 85f7ecca..af5502ae 100644 --- a/packages/stream_chat_flutter_core/lib/src/stream_channel.dart +++ b/packages/stream_chat_flutter_core/lib/src/stream_channel.dart @@ -17,7 +17,8 @@ enum QueryDirection { /// /// Use [StreamChannel.of] to get the current [StreamChannelState] instance. class StreamChannel extends StatefulWidget { - // ignore: public_member_api_docs + /// Creates a new instance of [StreamChannel]. Both [child] and [client] must + /// be supplied and not null. const StreamChannel({ Key key, @required this.child, diff --git a/packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart b/packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart index 3d23eb08..a37dfd54 100644 --- a/packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart @@ -49,6 +49,13 @@ class StreamChatCore extends StatefulWidget { @required this.child, }) : super(key: key); + /// Instance of Stream Chat Client containing information about the current + /// application. + final Client client; + + /// Widget descendant. + final Widget child; + @override StreamChatCoreState createState() => StreamChatCoreState(); diff --git a/packages/stream_chat_flutter_core/lib/src/users_bloc.dart b/packages/stream_chat_flutter_core/lib/src/users_bloc.dart index 5ada9d90..bef0cead 100644 --- a/packages/stream_chat_flutter_core/lib/src/users_bloc.dart +++ b/packages/stream_chat_flutter_core/lib/src/users_bloc.dart @@ -5,11 +5,18 @@ import 'package:stream_chat/stream_chat.dart'; import 'stream_chat_core.dart'; /// Widget dedicated to the management of a users list with pagination. +/// +/// [UsersBloc] can be access at anytime by using the static [of] method +/// using Flutter's [BuildContext]. +/// +/// API docs: https://getstream.io/chat/docs/flutter-dart/init_and_users/ class UsersBloc extends StatefulWidget { /// The widget child final Widget child; /// Instantiate a new UsersBloc + /// Instantiate a new [UsersBloc]. The parameter [child] must be supplied and + /// not null. const UsersBloc({ Key key, @required this.child,