added documentation

.gitignore

@@ -1,3 +1,4 @@
 .dart_tool
 .packages
 .env
+doc

lib/gitter_api.dart

@@ -19,15 +19,36 @@ part 'src/v1/rooms_resource.dart';
 part 'src/v1/stream_api.dart';
 part 'src/v1/user_resource.dart';
 
+/// Core instance of Gitter API.
+///
+/// ### Parameters
+///
+/// - `keys`: This takes instance of [ApiKeys] which you can use to serve
+/// your access token.
+///
+/// Checkout the [gitter docs](https://developer.gitter.im/docs/welcome)
 class GitterApi {
+  /// API Host.
   final host = 'api.gitter.im';
 
+  /// Contains accesstoken.
   final ApiKeys keys;
 
   V1 _v1;
 
+  /// Version one of this API.
+  /// This contains all the resources belongs
+  /// to version 1 of gitter api.
   V1 get v1 => _v1;
 
+  /// Creates a instance of [this]
+  ///
+  /// ## Parameters
+  ///
+  /// - `keys`: This takes instance of [ApiKeys] which you can use to serve
+  /// your access token.
+  ///
+  /// Checkout the [gitter docs](https://developer.gitter.im/docs/welcome)
   GitterApi(this.keys) {
     _v1 = V1(this);
   }

lib/src/api_keys.dart

@@ -1,16 +1,24 @@
 part of gitterapi;
 
+///
 class ApiKeys {
+  /// Authorization token required to connect to Gitter API.
   final String authToken;
 
+  /// Creates a instance of [this].
   const ApiKeys(this.authToken);
 
   /// Returns a instance of [ApiKeys]
   /// by fetching `authToken` from Environment.
   ///
   /// This looksup for `AUTH_TOKEN` env variable.
   ///
-  factory ApiKeys.fromEnv() {
-    return ApiKeys(String.fromEnvironment('AUTH_TOKEN'));
+  /// ### Parameters:
+  ///
+  /// - `tokenVar`: Specifies which env variable to look for token.
+  /// By default it looks for AUTH_TOKEN.
+  ///
+  factory ApiKeys.fromEnv({String tokenVar = 'AUTH_TOKEN'}) {
+    return ApiKeys(String.fromEnvironment(tokenVar));
   }
 }

lib/src/v1.dart

@@ -1,18 +1,30 @@
 part of gitterapi;
 
+/// Class of version 1 of gitter API
 class V1 extends Version {
   UserResource _userResource;
   RoomsResource _roomsResource;
   MessagesResource _messagesResource;
   GroupsResource _groupsResource;
   StreamApi _streamApi;
 
+  /// Serves methods to access [user-resources](https://developer.gitter.im/docs/user-resource).
   UserResource get userResource => _userResource;
+
+  /// Serves methods to access [rooms-resources](https://developer.gitter.im/docs/rooms-resource).
   RoomsResource get roomResource => _roomsResource;
+
+  /// Serves methods to access [messages-resources](https://developer.gitter.im/docs/messages-resource).
   MessagesResource get messageResource => _messagesResource;
+
+  /// Serves methods to access [groups-resources](https://developer.gitter.im/docs/groups-resource).
   GroupsResource get groupResource => _groupsResource;
+
+  /// The streaming API allows real-time access to rooms. [streaming-api](https://developer.gitter.im/docs/streaming-api).
   StreamApi get streamApi => _streamApi;
 
+  /// Creates a instance of [this].
+  ///
   V1(GitterApi api) : super(api, 'v1') {
     _userResource = UserResource(this);
     _roomsResource = RoomsResource(this);
@@ -21,6 +33,7 @@ class V1 extends Version {
     _streamApi = StreamApi(this);
   }
 
+  /// Sends a json request to server and returns [Result<T>].
   Future<Result<T>> _jsonRequest<T>(
     String path, {
     String method = 'GET',
@@ -70,6 +83,7 @@ class V1 extends Version {
     }
   }
 
+  /// Sends a request and returns [Stream<StreamEvent>].
   Future<Stream<StreamEvent>> _streamRequest(
     String path, {
     String method = 'GET',

lib/src/v1/groups_resource.dart

@@ -1,6 +1,8 @@
 part of gitterapi;
 
+/// Contains methods for [Group-Resources](https://developer.gitter.im/docs/groups-resource).
 class GroupsResource extends Resource<V1> {
+  /// Creates a instance of [this].
   GroupsResource(V1 v) : super(v, 'groups');
 
   /// List groups the current user is in.
@@ -9,11 +11,27 @@ class GroupsResource extends Resource<V1> {
   }
 
   /// List of rooms nested under the specified group.
+  ///
+  /// ### Parameters:
+  ///
+  /// - `groupId`: Id of the group.
+  ///
   Future<Result<List>> getRooms(String groupId) {
     return _v._jsonRequest<List>('$_path/$groupId/rooms');
   }
 
   /// Create room nested under the specified group.
+  ///
+  /// ### Parameters:
+  ///
+  /// - `groupId`: Id of the group.
+  /// - `name`: Room name.W
+  /// - `topic`: Room topic/description.
+  /// - `security`: Describes the backing object we get permissions from. (defaults to 'PUBLIC').
+  /// - `type`: null|'ONE_TO_ONE'|'GH_REPO'|'GH_ORG'|'GH_USER'.
+  /// - `linkPath`: Represents how we find the backing object given the type.
+  /// - `source`: Tracking info for stats.
+  ///
   Future<Result<Map>> createRoom(
     String groupId, {
     String name,

lib/src/v1/messages_resource.dart

@@ -1,19 +1,22 @@
 part of gitterapi;
 
+/// Creates methods for [Messages-resource](https://developer.gitter.im/docs/messages-resource).
 class MessagesResource extends Resource<V1> {
   MessagesResource(V1 v) : super(v, 'chatMessages');
 
   /// List of messages in a room.
   /// Returns [List<Map<String,dynamic>>].
   ///
-  /// ### All the parameters are optional:
+  /// ### Parameters
   ///
+  /// - `roomId`: Id of the room.
   /// - `skip`: Skip n messages (constrained to 5000 or less).
   /// - `beforeId`: Get messages before beforeId.
   /// - `afterId`: Get messages after afterId.
   /// - `aroundId`: Get messages around aroundId including this message.
   /// - `limit`: Maximum number of messages to return (constrained to 100 or less).
   /// - `q`: Search query.
+  ///
   Future<Result<List<dynamic>>> getMessages(
     String roomId, {
     int skip,
@@ -37,12 +40,20 @@ class MessagesResource extends Resource<V1> {
   }
 
   /// There is also a way to retrieve a single message using its id.
+  ///
+  /// ### Parameters:
+  ///
+  /// - `roomId`: Id of the room.
+  /// - `messageId`: Id of the message.
+  ///
   Future<Result<Map>> getSingleMessage(String roomId, String messageId) {
     return _v._jsonRequest<Map>('rooms/$roomId/$_path/$messageId');
   }
 
   /// Send a message to a room.
   ///
+  /// ### Parameters
+  ///
   /// - `text`: Required Body of the message.
   /// - `status`: Boolean, set to true to indicate that the message is a status update (what /me uses)
   ///
@@ -58,41 +69,19 @@ class MessagesResource extends Resource<V1> {
     );
   }
 
-  /// Update a message.
+  /// Update
+  ///
+  /// ### Parameters
   ///
+  /// - `roomId`: Id of the room.
+  /// - `messageId`: Id of the message.
   /// - `text`: Required Body of the message.
   ///
-  /// ### Response
-  /// ```
-  /// {
-  ///   "id": "533171eb7bfc1a0000000012",
-  ///   "text": "You should also check https://irc.gitter.im/ <3<3<3",
-  ///   "html": "You should also check <a href=\"https://irc.gitter.im/\" rel=\"nofollow\" target=\"_new\" class=\"link\">https://irc.gitter.im/</a> &lt;3&lt;3&lt;3",
-  ///   "sent": "2014-03-25T12:09:15.292Z",
-  ///   "editedAt": "2014-03-25T12:13:02.985Z",
-  ///   "fromUser": {
-  ///     "id": "53307734c3599d1de448e192",
-  ///     "username": "malditogeek",
-  ///     "displayName": "Mauro Pompilio",
-  ///     "url": "/malditogeek",
-  ///     "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?",
-  ///     "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?"
-  ///   },
-  ///   "unread": false,
-  ///   "readBy": 0,
-  ///   "urls": [
-  ///     {
-  ///       "url": "https://irc.gitter.im/"
-  ///     }
-  ///   ],
-  ///   "mentions": [],
-  ///   "issues": [],
-  ///   "meta": {},
-  ///   "v": 2
-  /// }
-  /// ```
   Future<Result<Map>> updateMessage(
-      String roomId, String messageId, String text) {
+    String roomId,
+    String messageId,
+    String text,
+  ) {
     return _v._jsonRequest<Map>(
       'rooms/$roomId/$_path/$messageId',
       method: 'PUT',
@@ -104,12 +93,25 @@ class MessagesResource extends Resource<V1> {
 
   /// You can retrieve unread items and
   /// mentions using the following endpoint.
+  ///
+  /// ### Parameters
+  ///
+  /// - `userId`: Id of the user.
+  /// - `roomId`: Id of the room.
+  ///
   Future<Result<Map>> getUnreadItems(String userId, String roomId) {
     return _v._jsonRequest<Map>('user/$userId/rooms/$roomId/unreadItems');
   }
 
   /// There is an additional endpoint nested under
   /// rooms that you can use to mark chat messages as read.
+  ///
+  /// ### Parameters
+  ///
+  /// - `userId`: Id of the user.
+  /// - `roomId`: Id of the room.
+  /// - `chatIds`: [List] of messageId's you want to mark as unread.
+  ///
   Future<Result<void>> markMessagesAsRead(
     String userId,
     String roomId, {