From 71542510edd64822621609e6542fef6dca8ce054 Mon Sep 17 00:00:00 2001
From: Ratakondala Arun <arunratakondala3470@gmail.com>
Date: Tue, 29 Dec 2020 22:42:59 +0530
Subject: [PATCH] added documentation
---
.gitignore | 1 +
lib/gitter_api.dart | 21 ++++++
lib/src/api_keys.dart | 12 ++-
lib/src/v1.dart | 14 ++++
lib/src/v1/groups_resource.dart | 18 +++++
lib/src/v1/messages_resource.dart | 66 +++++++++--------
lib/src/v1/rooms_resource.dart | 118 ++++++++++--------------------
lib/src/v1/stream_api.dart | 18 +++--
lib/src/v1/user_resource.dart | 56 ++++++++++++--
pubspec.lock | 37 +++++++++-
pubspec.yaml | 1 +
11 files changed, 234 insertions(+), 128 deletions(-)
diff --git a/.gitignore b/.gitignore
index 08a04c3..4eabe07 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
.dart_tool
.packages
.env
+doc
\ No newline at end of file
diff --git a/lib/gitter_api.dart b/lib/gitter_api.dart
index 26c2a81..80073d5 100644
--- a/lib/gitter_api.dart
+++ b/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);
}
diff --git a/lib/src/api_keys.dart b/lib/src/api_keys.dart
index 4f7be24..2b478c8 100644
--- a/lib/src/api_keys.dart
+++ b/lib/src/api_keys.dart
@@ -1,8 +1,11 @@
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]
@@ -10,7 +13,12 @@ class ApiKeys {
///
/// 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));
}
}
diff --git a/lib/src/v1.dart b/lib/src/v1.dart
index 9b6b200..6facbf6 100644
--- a/lib/src/v1.dart
+++ b/lib/src/v1.dart
@@ -1,5 +1,6 @@
part of gitterapi;
+/// Class of version 1 of gitter API
class V1 extends Version {
UserResource _userResource;
RoomsResource _roomsResource;
@@ -7,12 +8,23 @@ class V1 extends Version {
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',
diff --git a/lib/src/v1/groups_resource.dart b/lib/src/v1/groups_resource.dart
index 71f45a3..5de1f7d 100644
--- a/lib/src/v1/groups_resource.dart
+++ b/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,
diff --git a/lib/src/v1/messages_resource.dart b/lib/src/v1/messages_resource.dart
index 8559dc5..14371e6 100644
--- a/lib/src/v1/messages_resource.dart
+++ b/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> <3<3<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, {
diff --git a/lib/src/v1/rooms_resource.dart b/lib/src/v1/rooms_resource.dart
index ce9a636..4296c9a 100644
--- a/lib/src/v1/rooms_resource.dart
+++ b/lib/src/v1/rooms_resource.dart
@@ -1,54 +1,19 @@
part of gitterapi;
+/// Creates methods for [Rooms-resource](https://developer.gitter.im/docs/rooms-resource).
class RoomsResource extends Resource<V1> {
@override
String get _path => 'rooms';
+ /// Creates a instance of [this].
RoomsResource(V1 v) : super(v, 'rooms');
/// List rooms the current user is in.
///
- /// Returns [List<Map<String,dynamic>>].
+ /// ### Parameters:
+ ///
+ /// - `query`: Query to search for rooms.
///
- /// ### Response
- /// ```
- /// [
- /// {
- /// "id": "53307860c3599d1de448e19d",
- /// "name": "Andrew Newdigate",
- /// "topic": "",
- /// "oneToOne": true,
- /// "user": {
- /// "id": "53307831c3599d1de448e19a",
- /// "username": "suprememoocow",
- /// "displayName": "Andrew Newdigate",
- /// "url": "/suprememoocow",
- /// "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?",
- /// "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?"
- /// },
- /// "unreadItems": 0,
- /// "mentions": 0,
- /// "lurk": false,
- /// "url": "/suprememoocow",
- /// "githubType": "ONETOONE"
- /// },
- /// {
- /// "id": "5330777dc3599d1de448e194",
- /// "name": "gitterHQ",
- /// "topic": "Gitter",
- /// "uri": "gitterHQ",
- /// "oneToOne": false,
- /// "userCount": 2,
- /// "unreadItems": 0,
- /// "mentions": 0,
- /// "lastAccessTime": "2014-03-24T18:22:28.105Z",
- /// "lurk": false,
- /// "url": "/gitterHQ",
- /// "githubType": "ORG",
- /// "v": 1
- /// },
- /// ]
- /// ```
Future<Result<List<dynamic>>> rooms({String query}) {
return _v._jsonRequest<List<dynamic>>(
_path,
@@ -60,29 +25,33 @@ class RoomsResource extends Resource<V1> {
// TODO(@RatakondalaArun): Create a room
/// Fetches room id from uri.
- /// `uri` must not be null.
- /// ### Example:
+ ///
+ /// ### Parameters
+ ///
+ /// - `uri`: Room Uri must not be null.
+ ///
+ /// ### Example
/// ```
/// String uri = 'gitterhq/sandbox';
/// // remaining code ......
- ///final room = getRoomIdFrom(uri);
- /// ```
- /// ### Result:
- /// ```
- /// {
- /// "id": "52b42a52ed5ab0b3bf051b93",
- /// "name": "gitterHQ/sandbox",
- /// //...
- /// }
+ /// final room = getRoomIdFrom(uri);
/// ```
///
Future<Result<Map>> getRoomIdFrom(String uri) {
- return _v
- ._jsonRequest<Map>('$_path', method: 'POST', postData: {'uri': uri});
+ return _v._jsonRequest<Map>(
+ '$_path',
+ method: 'POST',
+ postData: {'uri': uri},
+ );
}
/// Join the room via ID.
- /// `userId` and `roomId` must not be null
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ /// - `roomId`: Id of the room.
+ ///
Future<Result<void>> joinRoom(String userId, String roomId) {
return _v._jsonRequest(
'user/$userId/$_path',
@@ -91,8 +60,13 @@ class RoomsResource extends Resource<V1> {
);
}
- /// Bans the give user form the room
- /// `roomId` and `username` must not be null.
+ /// Bans the give user form the room.
+ /// user must be a group admin to perform this action.
+ ///
+ /// ### Parameters
+ ///
+ /// - `roomId`: Id of the room.
+ /// - `username`: username. must not be null.
Future<Result<void>> banUserFromRoom(String roomId, String username) {
return _v._jsonRequest(
'$_path/$roomId/bans',
@@ -102,6 +76,7 @@ class RoomsResource extends Resource<V1> {
}
/// Update room details.
+ /// user must be group admin to perform this action.
///
/// ### Parameters
///
@@ -126,7 +101,13 @@ class RoomsResource extends Resource<V1> {
);
}
- ///Delete a room.
+ /// Delete a room.
+ /// user must be group admin to perform this action.
+ ///
+ /// ### Parameters
+ ///
+ /// - `roomId`: Id of the room.
+ ///
Future<Result<Map>> deleteRoom(String roomId) {
return _v._jsonRequest<Map>('$_path/$roomId', method: 'DELETE');
}
@@ -141,29 +122,6 @@ class RoomsResource extends Resource<V1> {
/// - `skip`: Skip n users.
/// - `limit`: maximum number of users to return (default 30).
///
- /// ### Response
- ///
- /// ```
- /// [
- /// {
- /// "id": "53307734c3599d1de448e192",
- /// "username": "malditogeek",
- /// "displayName": "Mauro Pompilio",
- /// "url": "/malditogeek",
- /// "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?",
- /// "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?",
- /// "role": "admin"
- /// },
- /// {
- /// "id": "53307831c3599d1de448e19a",
- /// "username": "suprememoocow",
- /// "displayName": "Andrew Newdigate",
- /// "url": "/suprememoocow",
- /// "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?",
- /// "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?"
- /// }
- /// ]
- /// ```
Future<Result<List<dynamic>>> getUsers(
String roomId, {
String query,
diff --git a/lib/src/v1/stream_api.dart b/lib/src/v1/stream_api.dart
index 6b2c58b..582767d 100644
--- a/lib/src/v1/stream_api.dart
+++ b/lib/src/v1/stream_api.dart
@@ -1,19 +1,27 @@
part of gitterapi;
-/// The JSON stream returns messages as JSON objects
-/// that are delimited by newline (\n). Space + newline
-/// (\n) are sent as periodic "keep-alive" messages to
-/// tell clients and NAT firewalls that the connection
-/// is still alive during low message volume periods.
+/// The streaming API allows real-time access to rooms.
+///
+/// This class methods sends [StreamEvent]s.
class StreamApi extends Resource<V1> {
StreamApi(V1 v) : super(v, 'rooms');
/// This returns chat message send by users in room.
+ ///
+ /// ### Parameters
+ ///
+ /// - `roomId`: Id of the room.
+ ///
Future<Stream<StreamEvent>> chatMessages(String roomId) async {
return _v._streamRequest('$_path/$roomId/chatMessages');
}
/// This returns room events.
+ ///
+ /// ### Parameters
+ ///
+ /// - `roomId`: Id of the room.
+ ///
Future<Stream<StreamEvent>> roomEvents(String roomId) async {
return _v._streamRequest('$_path/$roomId/events');
}
diff --git a/lib/src/v1/user_resource.dart b/lib/src/v1/user_resource.dart
index 51a00e7..a01e78b 100644
--- a/lib/src/v1/user_resource.dart
+++ b/lib/src/v1/user_resource.dart
@@ -1,22 +1,32 @@
part of gitterapi;
-/// This class contains the methods for userresources endpoint of gitter api.
-///
-/// [Check out the gitter documentation](https://developer.gitter.im/docs/user-resource)
+/// Creates methods for [User-resource](https://developer.gitter.im/docs/user-resource).
class UserResource extends Resource<V1> {
+ /// Creates a instance of [this].
UserResource(V1 v1) : super(v1, 'user');
- /// Returns a currently signed in user.
+ /// Returns currently signed in user.
Future<Result<Map>> me() {
return _v._jsonRequest<Map>('$_path/me');
}
/// List of Rooms the user is part of.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ ///
Future<Result<List<dynamic>>> getRooms(String userId) {
return _v._jsonRequest<List<dynamic>>('$_path/$userId/rooms');
}
/// Hide the room for the user.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ /// - `roomId`: Id of the room.
+ ///
Future<Result<void>> hideRoom(String userId, String roomId) {
return _v._jsonRequest<void>(
'$_path/$userId/rooms/$roomId',
@@ -24,14 +34,29 @@ class UserResource extends Resource<V1> {
);
}
- /// You can retrieve unread items and mentions using the following method.
+ /// You can retrieve unread items and mentions
+ /// using the following method.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ /// - `roomId`: Id of the room.
+ ///
Future<Result<Map>> getUnreadItems(String userId, String roomId) {
return _v._jsonRequest<Map>(
'$_path/$userId/rooms/$roomId/unreadItems',
);
}
- /// There is an additional method nested under rooms that you can use to mark chat messages as read.
+ /// There is an additional method 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 chat ids to marks them as read.
+ ///
Future<Result<void>> markUnReadItemsAsRead(
String userId,
String roomId,
@@ -44,19 +69,34 @@ class UserResource extends Resource<V1> {
);
}
- /// List of the user's GitHub Organisations and their respective Room if available.
+ /// List of the user's GitHub Organisations and their respective Room if available.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ ///
Future<Result<List<dynamic>>> getOrgs(String userId) {
return _v._jsonRequest<List<dynamic>>('$_path/$userId/orgs');
}
/// List of the user's GitHub Repositories and their respective Room if available.
///
- /// Note: It'll return private repositories if the current user has granted Gitter privileges to access them.
+ /// *Note: It'll return private repositories if the current user has granted Gitter privileges to access them.*
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ ///
Future<Result<List<dynamic>>> getRepos(String userId) {
return _v._jsonRequest<List<dynamic>>('$_path/$userId/repos');
}
/// List of Gitter channels nested under the current user.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ ///
Future<Result<List<dynamic>>> getChannels(String userId) {
return _v._jsonRequest<List<dynamic>>(
'$_path/$userId/channels',
diff --git a/pubspec.lock b/pubspec.lock
index 8f14196..bdb9f59 100644
--- a/pubspec.lock
+++ b/pubspec.lock
@@ -78,6 +78,13 @@ packages:
url: "https://pub.dartlang.org"
source: hosted
version: "2.1.5"
+ csslib:
+ dependency: transitive
+ description:
+ name: csslib
+ url: "https://pub.dartlang.org"
+ source: hosted
+ version: "0.16.2"
dart2_constant:
dependency: transitive
description:
@@ -85,6 +92,13 @@ packages:
url: "https://pub.dartlang.org"
source: hosted
version: "1.0.2+dart2"
+ dartdoc:
+ dependency: "direct dev"
+ description:
+ name: dartdoc
+ url: "https://pub.dartlang.org"
+ source: hosted
+ version: "0.38.0"
dio:
dependency: "direct main"
description:
@@ -113,6 +127,13 @@ packages:
url: "https://pub.dartlang.org"
source: hosted
version: "1.2.0"
+ html:
+ dependency: transitive
+ description:
+ name: html
+ url: "https://pub.dartlang.org"
+ source: hosted
+ version: "0.14.0+4"
http:
dependency: transitive
description:
@@ -162,6 +183,13 @@ packages:
url: "https://pub.dartlang.org"
source: hosted
version: "0.11.4"
+ markdown:
+ dependency: transitive
+ description:
+ name: markdown
+ url: "https://pub.dartlang.org"
+ source: hosted
+ version: "3.0.0"
matcher:
dependency: transitive
description:
@@ -183,6 +211,13 @@ packages:
url: "https://pub.dartlang.org"
source: hosted
version: "0.9.7"
+ mustache:
+ dependency: transitive
+ description:
+ name: mustache
+ url: "https://pub.dartlang.org"
+ source: hosted
+ version: "1.1.1"
node_interop:
dependency: transitive
description:
@@ -380,4 +415,4 @@ packages:
source: hosted
version: "2.2.1"
sdks:
- dart: ">=2.9.0 <3.0.0"
+ dart: ">=2.10.0 <3.0.0"
diff --git a/pubspec.yaml b/pubspec.yaml
index 34299fe..7d3a735 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -12,3 +12,4 @@ dependencies:
dev_dependencies:
test: ^1.15.7
dotenv: ^2.0.0
+ dartdoc: ^0.38.0