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

Update Core Documentation

packages/stream_chat_flutter_core/lib/src/channel_list_core.dart

@@ -11,6 +11,7 @@ import 'stream_chat_core.dart';
 /// [ChannelListCore] is a simplified class that allows fetching a list of channels while exposing UI builders.
 /// A [ChannelListController] is used to reload and paginate data.
 ///
+///
 /// ```dart
 /// class ChannelListPage extends StatelessWidget {
 ///   @override
@@ -50,20 +51,19 @@ import 'stream_chat_core.dart';
 /// }
 /// ```
 ///
-///
 /// Make sure to have a [StreamChatCore] ancestor in order to provide the information about the channels.
 class ChannelListCore extends StatefulWidget {
   /// Instantiate a new ChannelListView
   ChannelListCore({
     Key key,
-    this.filter,
-    this.options,
-    this.sort,
-    this.pagination,
     @required this.errorBuilder,
     @required this.emptyBuilder,
     @required this.loadingBuilder,
     @required this.listBuilder,
+    this.filter,
+    this.options,
+    this.sort,
+    this.pagination,
     this.channelListController,
   }) : super(key: key);
 

packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart

@@ -27,25 +27,22 @@ import 'message_search_bloc.dart';
 /// }
 /// ```
 ///
-///
 /// Make sure to have a [MessageSearchBloc] ancestor in order to provide the information about the messages.
 /// The widget uses a [ListView.separated] to render the list of messages.
 ///
-/// The widget components render the ui based on the first ancestor of type [StreamChatTheme].
-/// Modify it to change the widget appearance.
 class MessageSearchListCore extends StatefulWidget {
   /// Instantiate a new MessageSearchListView
   const MessageSearchListCore({
     Key key,
+    @required this.emptyBuilder,
+    @required this.errorBuilder,
+    @required this.loadingBuilder,
+    @required this.childBuilder,
     this.messageQuery,
     this.filters,
     this.sortOptions,
     this.paginationParams,
     this.messageFilters,
-    @required this.emptyBuilder,
-    @required this.errorBuilder,
-    @required this.loadingBuilder,
-    @required this.childBuilder,
     this.messageSearchListController,
   }) : super(key: key);
 

packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart

@@ -4,8 +4,14 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:stream_chat/stream_chat.dart';
 
-/// Widget used to provide information about the chat to the widget tree
+/// Widget used to provide information about the chat to the widget tree.
+/// This Widget is used to react to life cycle changes and system updates.
+/// When the app goes into the background, the websocket connection is kept alive
+/// for two minutes before being terminated.
 ///
+/// Conversely, when app is resumed or restarted, a new connection is initiated.
+///
+/// ```dart
 /// class MyApp extends StatelessWidget {
 ///   final Client client;
 ///
@@ -15,7 +21,7 @@ import 'package:stream_chat/stream_chat.dart';
 ///   Widget build(BuildContext context) {
 ///     return MaterialApp(
 ///       home: Container(
-///         child: StreamChat(
+///         child: StreamChatCore(
 ///           client: client,
 ///           child: ChannelListPage(),
 ///         ),
@@ -23,22 +29,25 @@ import 'package:stream_chat/stream_chat.dart';
 ///     );
 ///   }
 /// }
+/// ```
 ///
-/// Use [StreamChatCore.of] to get the current [StreamChatCoreState] instance.
 class StreamChatCore extends StatefulWidget {
-  // ignore: public_member_api_docs
+  /// Instance of Stream Chat Client containing information about the current
+  /// application.
   final Client client;
-  // ignore: public_member_api_docs
+
+  /// Widget descendant.
   final Widget child;
 
-  // ignore: public_member_api_docs
+  /// Constructor used for creating a new instance of [StreamChatCore].
+  ///
+  /// [StreamChatCore] is a stateful widget which reacts to system events and updates
+  /// Stream's connection status accordingly.
   StreamChatCore({
     Key key,
     @required this.client,
     @required this.child,
-  }) : super(
-          key: key,
-        );
+  }) : super(key: key);
 
   @override
   StreamChatCoreState createState() => StreamChatCoreState();
@@ -58,11 +67,12 @@ class StreamChatCore extends StatefulWidget {
   }
 }
 
-/// The current state of the StreamChat widget
+/// State class associated with [StreamChatCore].
 class StreamChatCoreState extends State<StreamChatCore>
     with WidgetsBindingObserver {
-  // ignore: public_member_api_docs
+  /// Initialized client used throughout the application.
   Client get client => widget.client;
+
   Timer _disconnectTimer;
 
   @override

packages/stream_chat_flutter_core/lib/src/user_list_core.dart

@@ -47,25 +47,25 @@ import 'package:stream_chat_flutter_core/src/users_bloc.dart';
 /// }
 /// ```
 ///
+/// [UsersBloc] must be the ancestor of this widget. This is necessary since
+/// [UserListCore] depends on functionality contained within [UsersBloc].
 ///
-/// Make sure to have a [UsersBloc] ancestor in order to provide the information about the users.
 /// The widget uses a [ListView.separated], [GridView.builder] to render the list, grid of channels.
-///
-/// The widget components render the ui based on the first ancestor of type [StreamChatTheme].
-/// Modify it to change the widget appearance.
+/// The parameters [listBuilder], [loadingBuilder], [emptyBuilder] and [errorBuilder] must all be supplied
+/// and not null.
 class UserListCore extends StatefulWidget {
-  /// Instantiate a new UserListView
+  /// Instantiate a new [UserListCore]
   const UserListCore({
     Key key,
+    @required this.errorBuilder,
+    @required this.emptyBuilder,
+    @required this.loadingBuilder,
+    @required this.listBuilder,
     this.filter,
     this.options,
     this.sort,
     this.pagination,
     this.groupAlphabetically = false,
-    @required this.errorBuilder,
-    @required this.emptyBuilder,
-    @required this.loadingBuilder,
-    @required this.listBuilder,
     this.userListController,
   }) : super(key: key);
 
@@ -138,9 +138,9 @@ class _UserListCoreState extends State<UserListCore>
 
   @override
   Widget build(BuildContext context) {
-    final usersBloc = UsersBloc.of(context);
+    final _usersBloc = UsersBloc.of(context);
 
-    return _buildListView(usersBloc);
+    return _buildListView(_usersBloc);
   }
 
   bool get isListAlreadySorted =>
@@ -207,9 +207,9 @@ class _UserListCoreState extends State<UserListCore>
   }
 
   void loadData() {
-    final usersBloc = UsersBloc.of(context);
+    final _usersBloc = UsersBloc.of(context);
 
-    usersBloc.queryUsers(
+    _usersBloc.queryUsers(
       filter: widget.filter,
       sort: widget.sort,
       pagination: widget.pagination,
@@ -218,13 +218,13 @@ class _UserListCoreState extends State<UserListCore>
   }
 
   void paginateData() {
-    final usersBloc = UsersBloc.of(context);
+    final _usersBloc = UsersBloc.of(context);
 
-    usersBloc.queryUsers(
+    _usersBloc.queryUsers(
       filter: widget.filter,
       sort: widget.sort,
       pagination: widget.pagination.copyWith(
-        offset: usersBloc.users?.length ?? 0,
+        offset: _usersBloc.users?.length ?? 0,
       ),
       options: widget.options,
     );
@@ -249,7 +249,9 @@ class _UserListCoreState extends State<UserListCore>
   }
 }
 
-// ignore: public_member_api_docs
+/// Represents an item in a the user stream list.
+/// Header items are prefixed with the key `HEADER` While users are prefixed with
+/// `USER`.
 abstract class ListItem {
   // ignore: public_member_api_docs
   String get key {

packages/stream_chat_flutter_core/lib/src/users_bloc.dart

@@ -4,7 +4,7 @@ import 'package:stream_chat/stream_chat.dart';
 
 import 'stream_chat_core.dart';
 
-/// Widget dedicated to the management of a users list with pagination
+/// Widget dedicated to the management of a users list with pagination.
 class UsersBloc extends StatefulWidget {
   /// The widget child
   final Widget child;
@@ -49,7 +49,9 @@ class UsersBlocState extends State<UsersBloc>
   /// The stream notifying the state of queryUsers call
   Stream<bool> get queryUsersLoading => _queryUsersLoadingController.stream;
 
-  /// Calls [Client.queryUsers] updating [queryUsersLoading] stream
+  /// The Query Users method allows you to search for users and see if they are
+  /// online/offline.
+  /// [API Reference](https://getstream.io/chat/docs/flutter-dart/query_users/?language=dart)
   Future<void> queryUsers({
     Map<String, dynamic> filter,
     List<SortOption> sort,