From 6aa72990be2bee76260d9ac4e531869637eaed43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Paul=20P=C3=A9rez?= Date: Sat, 9 Nov 2024 00:30:51 -0300 Subject: [PATCH] Refactor JsonKey class documentation to improve code readability and consistency --- json_annotation/lib/src/json_key.dart | 76 +++++++++++++-------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/json_annotation/lib/src/json_key.dart b/json_annotation/lib/src/json_key.dart index d7c97b65b..1dc7653bc 100644 --- a/json_annotation/lib/src/json_key.dart +++ b/json_annotation/lib/src/json_key.dart @@ -1,4 +1,4 @@ -// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file +// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. @@ -19,13 +19,13 @@ class JsonKey { final Object? defaultValue; /// If `true`, generated code will throw a [DisallowedNullValueException] if - /// the corresponding key exists, but the value is `null`. + /// the corresponding key exists, but its value is `null`. /// /// Note: this value does not affect the behavior of a JSON map *without* the /// associated key. /// /// If [disallowNullValue] is `true`, [includeIfNull] will be treated as - /// `false` to ensure compatibility between `toJson` and `fromJson`. + /// `false` to ensure consistency between `toJson` and `fromJson`. /// /// If both [includeIfNull] and [disallowNullValue] are set to `true` on the /// same field, an exception will be thrown during code generation. @@ -39,8 +39,9 @@ class JsonKey { /// type of the annotated field. /// /// When creating a class that supports both `toJson` and `fromJson` - /// (the default), you should also set [toJson] if you set [fromJson]. - /// Values returned by [toJson] should "round-trip" through [fromJson]. + /// (the default behavior), it is recommended to also set [toJson] if + /// [fromJson] is set. Values returned by [toJson] should "round-trip" + /// through [fromJson]. final Function? fromJson; /// `true` if the generator should ignore this field completely. @@ -48,7 +49,7 @@ class JsonKey { /// If `null` (the default) or `false`, the field will be considered for /// serialization. /// - /// This field is DEPRECATED use [includeFromJson] and [includeToJson] + /// This field is DEPRECATED; use [includeFromJson] and [includeToJson] /// instead. @Deprecated( 'Use `includeFromJson` and `includeToJson` with a value of `false` ' @@ -56,23 +57,23 @@ class JsonKey { ) final bool? ignore; - /// Used to force a field to be included (or excluded) when decoding a object - /// from JSON. + /// Determines whether a field should be included (or excluded) when decoding + /// an object from JSON. /// - /// `null` (the default) means the field will be handled with the default - /// semantics that take into account if it's private or if it can be cleanly - /// round-tripped to-from JSON. + /// `null` (the default) means the field will be handled with default + /// semantics that consider whether it's private or if it can be cleanly + /// round-tripped to and from JSON. /// - /// `true` means the field should always be decoded, even if it's private. + /// `true` forces the field to always be decoded, even if it's private. /// - /// `false` means the field should never be decoded. + /// `false` prevents the field from being decoded. final bool? includeFromJson; - /// Whether the generator should include fields with `null` values in the + /// Specifies whether fields with `null` values should be included in the /// serialized output. /// - /// If `true`, the generator should include the field in the serialized - /// output, even if the value is `null`. + /// If `true`, the field will be included in the serialized output even if its + /// value is `null`. /// /// The default value, `null`, indicates that the behavior should be /// acquired from the [JsonSerializable.includeIfNull] annotation on the @@ -85,44 +86,43 @@ class JsonKey { /// same field, an exception will be thrown during code generation. final bool? includeIfNull; - /// Used to force a field to be included (or excluded) when encoding a object - /// to JSON. + /// Determines whether a field should be included (or excluded) when encoding + /// an object to JSON. /// /// `null` (the default) means the field will be handled with the default /// semantics that take into account if it's private or if it can be cleanly /// round-tripped to-from JSON. /// - /// `true` means the field should always be encoded, even if it's private. + /// `true` forces the field to always be encoded, even if it's private. /// - /// `false` means the field should never be encoded. + /// `false` prevents the field from being encoded. final bool? includeToJson; - /// The key in a JSON map to use when reading and writing values corresponding - /// to the annotated fields. + /// The key to use in the JSON map when reading and writing values for the + /// annotated field. /// - /// If `null`, the field name is used. + /// If `null`, the field name will be used as the key. final String? name; - /// Specialize how a value is read from the source JSON map. + /// Customizes how a value is read from the source JSON map. /// /// Typically, the value corresponding to a given key is read directly from /// the JSON map using `map[key]`. At times it's convenient to customize this /// behavior to support alternative names or to support logic that requires /// accessing multiple values at once. /// - /// The provided, the [Function] must be a top-level or static within the - /// using class. + /// The provided [Function] must be either a top-level function or a static + /// method within the class. /// /// Note: using this feature does not change any of the subsequent decoding /// logic for the field. For instance, if the field is of type [DateTime] we /// expect the function provided here to return a [String]. final Object? Function(Map, String)? readValue; - /// When `true`, generated code for `fromJson` will verify that the source - /// JSON map contains the associated key. + /// If `true`, generated code for `fromJson` will verify that the source JSON + /// map contains the associated key. /// - /// If the key does not exist, a [MissingRequiredKeysException] exception is - /// thrown. + /// If the key is missing, a [MissingRequiredKeysException] will be thrown. /// /// Note: only the existence of the key is checked. A key with a `null` value /// is considered valid. @@ -135,23 +135,23 @@ class JsonKey { /// returns a JSON-compatible value. /// /// When creating a class that supports both `toJson` and `fromJson` - /// (the default), you should also set [fromJson] if you set [toJson]. - /// Values returned by [toJson] should "round-trip" through [fromJson]. + /// (the default behavior), it is recommended to also set [fromJson] if + /// [toJson] is set. Values returned by [toJson] should "round-trip" through + /// [fromJson]. final Function? toJson; - /// The value to use for an enum field when the value provided is not in the - /// source enum. + /// The value to use for an enum field when the provided value does not match + /// any of the values in the source enum. /// /// Valid only on enum fields with a compatible enum value. /// - /// If you want to use the value `null` when encountering an unknown value, - /// use the value of [JsonKey.nullForUndefinedEnumValue] instead. This is only - /// valid on a nullable enum field. + /// To use `null` for unknown values, use [JsonKey.nullForUndefinedEnumValue]. + /// This is only valid for nullable enum fields. final Enum? unknownEnumValue; /// Creates a new [JsonKey] instance. /// - /// Only required when the default behavior is not desired. + /// Use this constructor when the default behavior is not desired. const JsonKey({ @Deprecated('Has no effect') bool? nullable, this.defaultValue,