Add documentation for GitHubJson

axel-op · axel-op · commit b73f214eecb1 · 2020-03-16T23:45:55.000+01:00
diff --git a/lib/src/json.dart b/lib/src/json.dart
@@ -1,23 +1,47 @@
 import 'dart:convert';
 
 import 'package:github/src/common/util/utils.dart';
-import 'package:github/src/util.dart';
 
+/// Internal class for Json encoding
+/// that should be used instead of `dart:convert`.
+///
+/// It contains methods that ensures that converted Json
+/// will work with the GitHub API.
 class GitHubJson {
-  GitHubJson._();
+  const GitHubJson._();
 
+  /// Called only if an object is of a non primitive type.
+  ///
+  /// If [object] is a [DateTime], it converts it to a String whose format is compatible with the API.
+  /// Else, it uses the default behavior of [JsonEncoder] which is to call `toJson` method onto [object].
+  ///
+  /// If [object] is not a [DateTime] and don't have a `toJson` method, an exception will be thrown
+  /// but handled by [JsonEncoder].
+  /// Do not catch it.
   static dynamic _toEncodable(dynamic object) {
     if (object is DateTime) {
       return dateToGitHubIso8601(object);
     }
+    // `toJson` could return a [Map] or a [List],
+    // so we have to delete null values in them.
     return _checkObject(object.toJson());
   }
 
+  /// Encodes [object] to a Json String compatible with the GitHub API.
+  /// It should be used instead of `jsonEncode`.
+  ///
+  /// Equivalent to `jsonEncode` except that
+  /// it converts [DateTime] to a proper String for the GitHub API,
+  /// and it also deletes keys associated with null values in maps before converting them.
+  ///
+  /// The obtained String can be decoded using `jsonDecode`.
   static String encode(Object object, {String indent}) {
     final encoder = JsonEncoder.withIndent(indent, _toEncodable);
     return encoder.convert(_checkObject(object));
   }
 
+  /// Deletes keys associated with null values
+  /// in every map contained in [object].
   static dynamic _checkObject(dynamic object) {
     if (object is Map) {
       return createNonNullMap(object, recursive: true);
