Merge pull request #32 from RatakondalaArun/21-add-documentation

#21 add documentation

.gitignore

@@ -1,3 +1,6 @@
 .dart_tool
 .packages
 .env
+doc
+.markdownlint.yaml
+.todo

CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.0.1]
+
+- Initial Release

README.md

@@ -1,3 +1,38 @@
 # Gitter API Dart Warpper
 
-A simple warpper class around Gitter API
+A Dart client library for accessing [Gitter API](https://developer.gitter.im/docs/welcome).
+
+[![Gitter](https://badges.gitter.im/RatakondalaArun/gitterapi.svg)](https://gitter.im/RatakondalaArun/gitterapi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
+
+## Getting Started
+
+1) Add this to your `pubspec.yaml`
+
+    ```text
+    dependencies:
+        tmdb_api: recent_version.
+    ```
+
+2) Import the package in your code.
+
+    ```dart
+    import 'package:gitterapi/gitterapi.dart'
+    ```
+
+3) Create instance of `GitterApi`.
+
+   ```dart
+   final gitterApi = GitterApi(ApiKeys('ACCESS_TOKEN'));
+   ```
+
+### Example
+
+Now use that instance to make api requests.
+
+```dart
+final Result<Map> result = await gitterApi.v1.userResource.me(); 
+print(result.data);
+
+// you can use models from gitterapi/models.dart to parse this data
+final User me = User.fromMap(result.data);
+```

example/example.dart

@@ -0,0 +1,19 @@
+import 'package:gitterapi/gitter_api.dart';
+import 'package:gitterapi/models.dart';
+
+Future<void> main() async {
+  // Create a instance of GitterApi.
+  // In this case ApiKeys are being grabed from env.
+  final gitterApi = GitterApi(ApiKeys.fromEnv());
+  // Fetches current user.
+  final Result<Map> result = await gitterApi.v1.userResource.me();
+  // check if result is success.
+  if (result.isError) {
+    print('Some error occured error: ${result.error}');
+    return;
+  }
+  print(result.data);
+  // parse User from Map object.
+  final User me = User.fromMap(result.data);
+  print(me);
+}

lib/gitter_api.dart

@@ -1,3 +1,6 @@
+/// This library provides a easy way to intract with [Gitter API](https://developer.gitter.im/docs/welcome).
+///
+/// This library also provides models to convert responses.
 library gitterapi;
 
 import 'dart:convert';
@@ -19,15 +22,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/models.dart

@@ -3,6 +3,5 @@ export 'models/issue.dart';
 export 'models/mention.dart';
 export 'models/message.dart';
 export 'models/permission.dart';
-export 'models/provider.dart';
 export 'models/room.dart';
 export 'models/user.dart';

lib/models/group.dart

@@ -1,3 +1,4 @@
+/// Represents a group.
 class Group {
   /// Group ID.
   final String id;
@@ -14,6 +15,7 @@ class Group {
   /// Base avatar URL (add s parameter to size)
   final String avatarUrl;
 
+  /// Creates a instance of [Group].
   const Group({
     this.id,
     this.name,
@@ -70,9 +72,10 @@ class SecurityDescriptor {
   /// [null|'ONE_TO_ONE'|'GH_REPO'|'GH_ORG'|'GH_USER']
   final SecurityDescriptorType type;
 
-  /// Represents how we find the backing object given the type
+  /// Represents how we find the backing object given the type.
   final String linkPath;
 
+  /// Creates a instace of [SecurityDescriptor].
   const SecurityDescriptor({
     this.type,
     this.linkPath,
@@ -107,8 +110,16 @@ class SecurityDescriptor {
   String toString() => 'SecurityDescriptor(type: $type, linkPath: $linkPath)';
 }
 
-enum SecurityDescriptorType { oneToOne, ghRepo, ghOrg, ghUser, glGroup }
+/// Security descriptorType. Describes the backing object we get permissions from.
+enum SecurityDescriptorType {
+  oneToOne,
+  ghRepo,
+  ghOrg,
+  ghUser,
+  glGroup,
+}
 
+/// This can be used to convert [SecurityDescriptorType] to [String] and back.
 extension SecurityDescriptorTypeExtension on SecurityDescriptorType {
   Map<SecurityDescriptorType, String> get names {
     return {

lib/models/issue.dart

@@ -1,6 +1,9 @@
+/// Represents a issue.
 class Issue {
+  /// Issues number that was mentioned.
   final String number;
 
+  /// Creates a instance of [Issue].
   const Issue({
     this.number,
   });

lib/models/mention.dart

@@ -1,7 +1,12 @@
+/// Represents mention.
 class Mention {
+  /// Id of the user that was mentioned.
   final String userId;
+
+  /// Screen name of the user that was mentioned.
   final String screenName;
 
+  /// Creates a instance of [Mention].
   const Mention({
     this.userId,
     this.screenName,

lib/models/message.dart

@@ -2,6 +2,7 @@ import 'issue.dart';
 import 'mention.dart';
 import 'user.dart';
 
+/// Represents a Message.
 class Message {
   ///  ID of the message.
   final String id;
@@ -18,7 +19,7 @@ class Message {
   ///  ISO formatted date of the message if edited.
   final String editedAt;
 
-  ///  (User)[user-resource] that sent the message.
+  ///  (User) that sent the message.
   final User fromUser;
 
   ///  Boolean that indicates if the current user has read the message.
@@ -39,14 +40,17 @@ class Message {
   ///  Metadata. This is currently not used for anything.
   final List<dynamic> meta;
 
+  /// Converts [sent] to [DateTime].
   DateTime get sentAs {
     return sent == null ? null : DateTime.tryParse(sent);
   }
 
+  /// Converts [editedAt] to [DateTime].
   DateTime get editedAtAs {
     return editedAt == null ? null : DateTime.tryParse(editedAt);
   }
 
+  /// Creates a instance of [Message].
   const Message({
     this.id,
     this.text,

lib/models/permission.dart

@@ -1,9 +1,12 @@
 import 'dart:convert';
 
+/// This class contains user permissions.
 class Permissions {
+  /// Returns true if this person is admin.
   final bool admin;
 
-  Permissions({
+  /// Creates a instance of [Permissions].
+  const Permissions({
     this.admin,
   });
 

lib/models/room.dart

@@ -1,31 +1,6 @@
 import 'permission.dart';
 
-// {
-//       "id": "576c4d75c2f0db084a1f99ae",
-//       "name": "flutter/flutter",
-//       "topic": "Flutter makes it easy and fast to build beautiful apps for mobile and beyond.\n",
-//       "avatarUrl": "https://avatars-01.gitter.im/group/iv/4/576c4d75c2f0db084a1f99ad",
-//       "uri": "flutter/flutter",
-//       "oneToOne": false,
-//       "userCount": 12301,
-//       "unreadItems": 17,
-//       "mentions": 0,
-//       "lastAccessTime": "2020-12-16T17:14:05.771Z",
-//       "lurk": false,
-//       "url": "/flutter/flutter",
-//       "githubType": "REPO",
-//       "security": "PUBLIC",
-//       "noindex": false,
-//       "tags": [],
-//       "permissions": {
-//           "admin": false
-//       },
-//       "roomMember": true,
-//       "groupId": "576c4d75c2f0db084a1f99ad",
-//       "public": true,
-//       "v": 2
-//   },
-
+/// Represents a room.
 class Room {
   ///Room ID.
   final String id;
@@ -85,6 +60,7 @@ class Room {
   /// Wheather be indexed by search engines.
   final bool noindex;
 
+  /// Permissions user have in this room.
   final Permissions permissions;
 
   /// Room version.
@@ -100,6 +76,7 @@ class Room {
     );
   }
 
+  /// Creates a instance of [Room].
   const Room({
     this.id,
     this.name,
@@ -232,15 +209,29 @@ class Room {
   }
 }
 
+/// Type of room.
 enum RoomType {
+  /// This room is belonged to organization.
   org,
+
+  /// This room is belonged to Repository.
   repo,
+
+  /// This room is a one to one chat( Direct message ).
   oneToOne,
+
+  /// This is a Organization channel
   orgChannel,
+
+  /// This is a Repository channel
   repoChannel,
+
+  /// This is a User channel
   userChannel,
 }
 
+/// Extension on [RoomType]. Used to parse [RoomType] to [String]
+/// and back.
 extension RoomTypeExtension on RoomType {
   /// Returns [Map<RoomType,String>] with respect to there string.
   static const names = {

lib/models/user.dart

@@ -25,10 +25,13 @@ class User {
   /// Auth Provider
   final List<String> providers;
 
+  /// Version
   final int v;
 
+  /// Gavavatar version
   final String gv;
 
+  /// Creates a instance of [User]
   const User({
     this.id,
     this.username,

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));
   }
 }