Merge pull request #671 from appwrite/feat-flutter-dart-docs

Add inline doc comments to the Dart and Flutter SDKs

templates/dart/README.md.twig

@@ -2,7 +2,7 @@
 
 [![pub package](https://img.shields.io/pub/v/{{ language.params.packageName }}.svg?style=flat-square)](https://pub.dartlang.org/packages/{{ language.params.packageName }})
 ![License](https://img.shields.io/github/license/{{ sdk.gitUserName|url_encode }}/{{ sdk.gitRepoName|url_encode }}.svg?style=flat-square)
-![Version](https://img.shields.io/badge/api%20version-{{ spec.version|url_encode }}-blue.svg?style=flat-square)
+![Version](https://img.shields.io/badge/api%20version-{{spec.version | split('.') | slice(0,2) | join('.') ~ '.x' | url_encode}}-blue.svg?style=flat-square)
 [![Build Status](https://img.shields.io/travis/com/appwrite/sdk-generator?style=flat-square)](https://travis-ci.com/appwrite/sdk-generator)
 {% if sdk.twitterHandle %}
 [![Twitter Account](https://img.shields.io/twitter/follow/{{ sdk.twitterHandle }}?color=00acee&label=twitter&style=flat-square)](https://twitter.com/{{ sdk.twitterHandle }})

templates/dart/lib/id.dart.twig

@@ -1,13 +1,16 @@
 part of {{ language.params.packageName }};
 
+/// Helper class to generate ID strings for resources.
 class ID {
-    ID._();
-
-    static String unique() {
-        return 'unique()';
-    }
+  ID._();
 
-    static String custom(String id) {
-        return id;
-    }
+  /// Have Appwrite generate a unique ID for you.
+  static String unique() {
+    return 'unique()';
+  }
+
+  /// Uses [id] as the ID for the resource.
+  static String custom(String id) {
+    return id;
+  }
 }

templates/dart/lib/models.dart.twig

@@ -1,3 +1,4 @@
+/// {{spec.title | caseUcfirst}} Models
 library {{ language.params.packageName }}.models;
 
 part 'src/models/model.dart';

templates/dart/lib/package.dart.twig

@@ -1,3 +1,8 @@
+/// {{spec.title | caseUcfirst}} {{sdk.name}} SDK
+///
+/// This SDK is compatible with Appwrite server version {{spec.version | split('.') | slice(0,2) | join('.') ~ '.x' }}. 
+/// For older versions, please check
+/// [previous releases](https://github.com/{{sdk.gitUserName}}/{{sdk.gitRepoName}}/releases).
 library {{ language.params.packageName }};
 
 import 'dart:async';

templates/dart/lib/permission.dart.twig

@@ -1,21 +1,34 @@
 part of {{ language.params.packageName }};
 
+/// Helper class to generate permission strings for resources.
 class Permission {
-    Permission._();
+  Permission._();
 
-    static String read(String role) {
-        return 'read("$role")';
-    }
-    static String write(String role) {
-        return 'write("$role")';
-    }
-    static String create(String role) {
-        return 'create("$role")';
-    }
-    static String update(String role) {
-        return 'update("$role")';
-    }
-    static String delete(String role) {
-        return 'delete("$role")';
-    }
+  /// Read permission for provided [role]
+  static String read(String role) {
+    return 'read("$role")';
+  }
+
+  /// Write permission for provided [role]
+  ///
+  /// This is an alias of update, delete, and possibly create.
+  /// Don't use write in combination with update, delete, or create.
+  static String write(String role) {
+    return 'write("$role")';
+  }
+
+  /// Create permission for provided [role]
+  static String create(String role) {
+    return 'create("$role")';
+  }
+
+  /// Update permission for provided [role]
+  static String update(String role) {
+    return 'update("$role")';
+  }
+
+  /// Delete permission for provided [role]
+  static String delete(String role) {
+    return 'delete("$role")';
+  }
 }

templates/dart/lib/query.dart.twig

@@ -1,61 +1,117 @@
 part of {{ language.params.packageName }};
 
+/// Helper class to generate query strings.
 class Query {
-    Query._();
-
+  Query._();
+
+  /// Filter resources where [attribute] is equal to [value].
+  /// 
+  /// [value] can be a single value or a list. If a list is used
+  /// the query will return resources where [attribute] is equal
+  /// to any of the values in the list.
   static String equal(String attribute, dynamic value) =>
       _addQuery(attribute, 'equal', value);
 
+  /// Filter resources where [attribute] is not equal to [value].
+  ///
+  /// [value] can be a single value or a list. If a list is used
+  /// the query will return resources where [attribute] is equal
+  /// to any of the values in the list.
   static String notEqual(String attribute, dynamic value) =>
       _addQuery(attribute, 'notEqual', value);
 
+  /// Filter resources where [attribute] is less than [value].
+  ///
+  /// [value] can be a single value or a list. If a list is used
+  /// the query will return resources where [attribute] is equal
+  /// to any of the values in the list.
   static String lessThan(String attribute, dynamic value) =>
       _addQuery(attribute, 'lessThan', value);
 
+  /// Filter resources where [attribute] is less than or equal to [value].
+  ///
+  /// [value] can be a single value or a list. If a list is used
+  /// the query will return resources where [attribute] is equal
+  /// to any of the values in the list.
   static String lessThanEqual(String attribute, dynamic value) =>
       _addQuery(attribute, 'lessThanEqual', value);
 
+  /// Filter resources where [attribute] is greater than [value].
+  ///
+  /// [value] can be a single value or a list. If a list is used
+  /// the query will return resources where [attribute] is equal
+  /// to any of the values in the list.
   static String greaterThan(String attribute, dynamic value) =>
       _addQuery(attribute, 'greaterThan', value);
 
+  /// Filter resources where [attribute] is greater than or equal to [value].
+  ///
+  /// [value] can be a single value or a list. If a list is used
+  /// the query will return resources where [attribute] is equal
+  /// to any of the values in the list.
   static String greaterThanEqual(String attribute, dynamic value) =>
       _addQuery(attribute, 'greaterThanEqual', value);
 
+  /// Filter resources where by searching [attribute] for [value].
+  /// 
+  /// A fulltext index on [attribute] is required for this query to work.
   static String search(String attribute, String value) =>
       _addQuery(attribute, 'search', value);
 
+  /// Filter resources where [attribute] is null.
   static String isNull(String attribute) => 'isNull("$attribute")';
 
+  /// Filter resources where [attribute] is not null.
   static String isNotNull(String attribute) => 'isNotNull("$attribute")';
 
+  /// Filter resources where [attribute] is between [start] and [end] (inclusive).
   static String between(String attribute, dynamic start, dynamic end) =>
       _addQuery(attribute, 'between', [start, end]);
 
+  /// Filter resources where [attribute] starts with [value].
   static String startsWith(String attribute, String value) =>
       _addQuery(attribute, 'startsWith', value);
 
+  /// Filter resources where [attribute] ends with [value].
   static String endsWith(String attribute, String value) =>
       _addQuery(attribute, 'endsWith', value);
 
-  static String select(List<String> attributes) => 'select([${attributes.map((attr) => "\"$attr\"").join(",")}])';
+  /// Specify which attributes should be returned by the API call.
+  static String select(List<String> attributes) =>
+      'select([${attributes.map((attr) => "\"$attr\"").join(",")}])';
 
+  /// Sort results by [attribute] ascending.
   static String orderAsc(String attribute) => 'orderAsc("$attribute")';
 
+  /// Sort results by [attribute] descending.
   static String orderDesc(String attribute) => 'orderDesc("$attribute")';
 
+  /// Return results before [id].
+  /// 
+  /// Refer to the [Cursor Based Pagination]({{sdk.url}}/docs/pagination#cursor-pagination)
+  /// docs for more information.
   static String cursorBefore(String id) => 'cursorBefore("$id")';
 
+  /// Return results after [id].
+  /// 
+  /// Refer to the [Cursor Based Pagination]({{sdk.url}}/docs/pagination#cursor-pagination)
+  /// docs for more information.
   static String cursorAfter(String id) => 'cursorAfter("$id")';
 
+  /// Return only [limit] results.
   static String limit(int limit) => 'limit($limit)';
 
+  /// Return results from [offset].
+  /// 
+  /// Refer to the [Offset Pagination]({{sdk.url}}/docs/pagination#offset-pagination)
+  /// docs for more information.
   static String offset(int offset) => 'offset($offset)';
 
   static String _addQuery(String attribute, String method, dynamic value) => (value
           is List)
-      ? '$method("$attribute", [${value.map((item) => parseValues(item)).join(",")}])'
-      : '$method("$attribute", [${parseValues(value)}])';
+      ? '$method("$attribute", [${value.map((item) => _parseValues(item)).join(",")}])'
+      : '$method("$attribute", [${_parseValues(value)}])';
 
-  static String parseValues(dynamic value) =>
+  static String _parseValues(dynamic value) =>
       (value is String) ? '"$value"' : '$value';
-}
+}

templates/dart/lib/role.dart.twig

@@ -1,37 +1,60 @@
 part of {{ language.params.packageName }};
 
+/// Helper class to generate role strings for [Permission].
 class Role {
     Role._();
 
+    /// Grants access to anyone.
+    /// 
+    /// This includes authenticated and unauthenticated users.
     static String any() {
         return 'any';
     }
 
+    /// Grants access to a specific user by user ID.
+    /// 
+    /// You can optionally pass verified or unverified for
+    /// [status] to target specific types of users.
     static String user(String id, [String status = '']) {
         if(status.isEmpty) {
             return 'user:$id';
         }
         return 'user:$id/$status';
     }
 
+    /// Grants access to any authenticated or anonymous user.
+    /// 
+    /// You can optionally pass verified or unverified for
+    /// [status] to target specific types of users.
     static String users([String status = '']) {
         if(status.isEmpty) {
             return 'users';
         }
         return 'users/$status';
     }
 
+    /// Grants access to any guest user without a session.
+    /// 
+    /// Authenticated users don't have access to this role.
     static String guests() {
         return 'guests';
     }
 
+    /// Grants access to a team by team ID.
+    /// 
+    /// You can optionally pass a role for [role] to target
+    /// team members with the specified role.
     static String team(String id, [String role = '']) {
         if(role.isEmpty) {
             return 'team:$id';
         }
         return 'team:$id/$role';
     }
 
+    /// Grants access to a specific member of a team.
+    /// 
+    /// When the member is removed from the team, they will
+    /// no longer have access.
     static String member(String id) {
         return 'member:$id';
     }

templates/dart/lib/services/service.dart.twig

@@ -8,17 +8,16 @@ part of {{ language.params.packageName }};
 {% endmacro %}
 
 {%if service.description %}
-{{- service.description|dartComment}}
+{{- service.description|dartComment | split('    ///') | join('///')}}
 {% endif %}
 class {{ service.name | caseUcfirst }} extends Service {
     {{ service.name | caseUcfirst }}(super.client);
-
 {% for method in service.methods %}
+
     /// {{ method.title }}
-{%~ if method.description %}
     ///
+{%~ if method.description %}
 {{ method.description | dartComment }}
-    ///
 {% endif %}
     {% if method.type == 'location' %}Future<Uint8List>{% else %}{% if method.responseModel and method.responseModel != 'any' %}Future<models.{{method.responseModel | caseUcfirst | overrideIdentifier}}>{% else %}Future{% endif %}{% endif %} {{ method.name | caseCamel }}({{ _self.method_parameters(method.parameters.all, method.consumes) }}) async {
         final String path = '{{ method.path }}'{% for parameter in method.parameters.path %}.replaceAll('{{ '{' }}{{ parameter.name | caseCamel }}{{ '}' }}', {{ parameter.name | caseCamel | overrideIdentifier }}){% endfor %};
@@ -30,7 +29,6 @@ class {{ service.name | caseUcfirst }} extends Service {
 {% else %}
 {{ include('dart/base/requests/api.twig') }}
 {% endif %}
-
     }
 {% endfor %}
 }

templates/dart/lib/src/client.dart.twig

@@ -5,31 +5,47 @@ import 'client_stub.dart'
 import 'response.dart';
 import 'upload_progress.dart';
 
+/// [Client] that handles requests to {{spec.title | caseUcfirst}}
 abstract class Client {
+  /// The size for cunked uploads in bytes.
   static const int CHUNK_SIZE = 5*1024*1024;
+
+  /// Holds configuration such as project.
   late Map<String, String> config;
   late String _endPoint;
 
+  /// {{spec.title | caseUcfirst}} endpoint.
   String get endPoint => _endPoint;
 
+  /// Initializes a [Client].
   factory Client(
           {String endPoint = '{{ spec.endpoint }}',
           bool selfSigned = false}) =>
       createClient(endPoint: endPoint, selfSigned: selfSigned);
 
+  /// Set self signed to [status].
+  /// 
+  /// If self signed is true, [Client] will ignore invalid certificates.
+  /// This is helpful in environments where your {{spec.title | caseUcfirst}}
+  /// instance does not have a valid SSL certificate.
   Client setSelfSigned({bool status = true});
 
+  /// Set the {{spec.title | caseUcfirst}} endpoint.
   Client setEndpoint(String endPoint);
 
 {% for header in spec.global.headers %}
+  /// Set {{header.key | caseUcfirst}}
 {% if header.description %}
+  ///
   /// {{header.description}}
 {% endif %}
   Client set{{header.key | caseUcfirst}}(value);
-{% endfor %}
 
+{% endfor %}
+  /// Add headers that should be sent with all API calls.
   Client addHeader(String key, String value);
 
+  /// Upload a file in chunks.
   Future<Response> chunkedUpload({
     required String path,
     required Map<String, dynamic> params,
@@ -39,6 +55,7 @@ abstract class Client {
     Function(UploadProgress)? onProgress,
   });
 
+  /// Send the API request.
   Future<Response> call(HttpMethod method, {
     String path = '',
     Map<String, String> headers = const {},

templates/dart/lib/src/enums.dart.twig

@@ -1,6 +1,8 @@
+/// HTTP methods.
 enum HttpMethod { get, post, put, delete, patch }
 
 extension HttpMethodString on HttpMethod {
+  /// Returns the HTTP method in all caps.
   String name() {
     return toString().split('.').last.toUpperCase();
   }