Merge pull request #245 from GetStream/nash/core-docs

Improve Core package docs

packages/stream_chat_flutter_core/lib/src/channel_list_core.dart

@@ -257,11 +257,14 @@ class _ChannelListCoreState extends State<ChannelListCore>
   }
 }
 
-/// 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;
 }

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;
 
@@ -19,15 +37,6 @@ class ChannelsBloc extends StatefulWidget {
   /// Function used to evaluate if a channel should be added to the list when a message.new event is received
   final bool Function(Event) shouldAddChannel;
 
-  /// Instantiate a new ChannelsBloc
-  const ChannelsBloc({
-    Key key,
-    this.child,
-    this.lockChannelsOrder = false,
-    this.channelsComparator,
-    this.shouldAddChannel,
-  }) : super(key: key);
-
   @override
   ChannelsBlocState createState() => ChannelsBlocState();
 
@@ -45,7 +54,7 @@ class ChannelsBloc extends StatefulWidget {
   }
 }
 
-/// The current state of the [ChannelsBloc]
+/// The current state of the [ChannelsBloc].
 class ChannelsBlocState extends State<ChannelsBloc>
     with AutomaticKeepAliveClientMixin {
   @override

packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart

@@ -3,9 +3,24 @@ 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 {
+  /// Creates a new instance of [LazyLoadScrollView]. The parameter [child] must be
+  /// supplied and not null.
+  const LazyLoadScrollView({
+    Key key,
+    @required this.child,
+    this.onStartOfPage,
+    this.onEndOfPage,
+    this.onPageScrollStart,
+    this.onPageScrollEnd,
+    this.onInBetweenOfPage,
+    this.isLoading = false,
+    this.scrollOffset = 100,
+  })  : assert(child != null),
+        super(key: key);
+
   /// The [Widget] that this widget watches for changes on
   final Widget child;
 
@@ -27,23 +42,9 @@ 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
-  const LazyLoadScrollView({
-    Key key,
-    @required this.child,
-    this.onStartOfPage,
-    this.onEndOfPage,
-    this.onPageScrollStart,
-    this.onPageScrollEnd,
-    this.onInBetweenOfPage,
-    this.isLoading = false,
-    this.scrollOffset = 100,
-  })  : assert(child != null),
-        super(key: key);
-
   @override
   State<StatefulWidget> createState() => _LazyLoadScrollViewState();
 }

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

packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart

@@ -4,17 +4,23 @@ 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;
-
   /// Instantiate a new MessageSearchBloc
   const MessageSearchBloc({
     Key key,
     @required this.child,
   }) : super(key: key);
 
+  /// The widget child
+  final Widget child;
+
   @override
   MessageSearchBlocState createState() => MessageSearchBlocState();
 

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,

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,

packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart

@@ -32,13 +32,6 @@ import 'package:stream_chat/stream_chat.dart';
 /// ```
 ///
 class StreamChatCore extends StatefulWidget {
-  /// Instance of Stream Chat Client containing information about the current
-  /// application.
-  final Client client;
-
-  /// Widget descendant.
-  final Widget child;
-
   /// Constructor used for creating a new instance of [StreamChatCore].
   ///
   /// [StreamChatCore] is a stateful widget which reacts to system events and updates
@@ -49,6 +42,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();
 

packages/stream_chat_flutter_core/lib/src/users_bloc.dart

@@ -5,16 +5,22 @@ 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,
   }) : super(key: key);
 
+  /// The widget child
+  final Widget child;
+
   @override
   UsersBlocState createState() => UsersBlocState();