From 2430eb09de4bdaf59afa8246603937c049f71a21 Mon Sep 17 00:00:00 2001 From: Ratakondala Arun Date: Wed, 30 Dec 2020 11:58:17 +0530 Subject: [PATCH] Add Documentation closes #21 --- lib/gitter_api.dart | 3 +++ lib/models.dart | 1 - lib/models/group.dart | 15 +++++++++++-- lib/models/issue.dart | 3 +++ lib/models/mention.dart | 5 +++++ lib/models/message.dart | 6 +++++- lib/models/permission.dart | 5 ++++- lib/models/room.dart | 43 +++++++++++++++----------------------- lib/models/user.dart | 3 +++ 9 files changed, 53 insertions(+), 31 deletions(-) diff --git a/lib/gitter_api.dart b/lib/gitter_api.dart index 80073d5..6fb25f2 100644 --- a/lib/gitter_api.dart +++ b/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'; diff --git a/lib/models.dart b/lib/models.dart index 3f1bfb5..cdad657 100644 --- a/lib/models.dart +++ b/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'; diff --git a/lib/models/group.dart b/lib/models/group.dart index 4be8cf7..5e3321d 100644 --- a/lib/models/group.dart +++ b/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 get names { return { diff --git a/lib/models/issue.dart b/lib/models/issue.dart index 13a24ae..d4914fd 100644 --- a/lib/models/issue.dart +++ b/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, }); diff --git a/lib/models/mention.dart b/lib/models/mention.dart index 3f3c649..cea3e0b 100644 --- a/lib/models/mention.dart +++ b/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, diff --git a/lib/models/message.dart b/lib/models/message.dart index b3bd75e..451937b 100644 --- a/lib/models/message.dart +++ b/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 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, diff --git a/lib/models/permission.dart b/lib/models/permission.dart index cc5410c..83fdbf6 100644 --- a/lib/models/permission.dart +++ b/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, }); diff --git a/lib/models/room.dart b/lib/models/room.dart index 90f1a48..63cebaf 100644 --- a/lib/models/room.dart +++ b/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] with respect to there string. static const names = { diff --git a/lib/models/user.dart b/lib/models/user.dart index c20311b..4acee85 100644 --- a/lib/models/user.dart +++ b/lib/models/user.dart @@ -25,10 +25,13 @@ class User { /// Auth Provider final List providers; + /// Version final int v; + /// Gavavatar version final String gv; + /// Creates a instance of [User] const User({ this.id, this.username,