squash! comments wip

Signed-off-by: Zixuan James Li <[email protected]>

Author: PIG208

lib/api/model/polls.dart

@@ -2,21 +2,27 @@ import 'package:json_annotation/json_annotation.dart';
 
 part 'polls.g.dart';
 
+// const maxLatestOptionIndex = 1000; // TODO validate
+
 /// Data structure seen from [Submessage.content] to support Zulip's widget
 /// system.
 sealed class WidgetData {}
 
+/// [WidgetData] that defines the starting state of the poll.
+///
+/// If a message contains a poll, the first [Submessage] from
+/// [Message.submessages] should always be a [PollStartData].
 @JsonSerializable(fieldRename: FieldRename.snake)
-class WidgetStartData extends WidgetData {
-  WidgetStartData({required this.widgetType, required this.extraData});
+class PollStartData extends WidgetData {
+  PollStartData({required this.widgetType, required this.extraData});
 
   final WidgetType widgetType;
   final PollExtraData extraData;
 
-  factory WidgetStartData.fromJson(Map<String, dynamic> json) =>
-    _$WidgetStartDataFromJson(json);
+  factory PollStartData.fromJson(Map<String, dynamic> json) =>
+    _$PollStartDataFromJson(json);
 
-  Map<String, dynamic> toJson() => _$WidgetStartDataToJson(this);
+  Map<String, dynamic> toJson() => _$PollStartDataToJson(this);
 }
 
 @JsonSerializable(fieldRename: FieldRename.snake)
@@ -55,18 +61,21 @@ sealed class PollEvent extends WidgetData {
   Map<String, dynamic> toJson();
 }
 
+/// Event when an option is added to the poll.
 @JsonSerializable(fieldRename: FieldRename.snake)
 class PollOptionEvent extends PollEvent {
   @override
   @JsonKey(includeToJson: true)
   PollEventType get type => PollEventType.newOption;
 
   final String option;
-  final int idx;
+  /// The index of the latest option added by a specific user.
+  @JsonKey(name: 'idx')
+  final int latestOptionIndex;
 
   PollOptionEvent({
     required this.option,
-    required this.idx,
+    required this.latestOptionIndex,
   });
 
   @override
@@ -77,6 +86,7 @@ class PollOptionEvent extends PollEvent {
   Map<String, dynamic> toJson() => _$PollOptionEventToJson(this);
 }
 
+/// Event when the question of the poll has been edited.
 @JsonSerializable(fieldRename: FieldRename.snake)
 class PollQuestionEvent extends PollEvent {
   @override
@@ -97,18 +107,22 @@ class PollQuestionEvent extends PollEvent {
   Map<String, dynamic> toJson() => _$PollQuestionEventToJson(this);
 }
 
+/// Event when a vote has been casted or removed.
 @JsonSerializable(fieldRename: FieldRename.snake)
 class PollVoteEvent extends PollEvent {
   @override
   @JsonKey(includeToJson: true)
   PollEventType get type => PollEventType.vote;
 
+  /// Key corresponding to an option in the `'${sender_id},{latestOptionIndex}'`
+  /// format.
   final String key;
-  final int vote;
+  @JsonKey(name: 'vote', unknownEnumValue: VoteOp.unknown)
+  final VoteOp op;
 
   PollVoteEvent({
     required this.key,
-    required this.vote,
+    required this.op,
   });
 
   @override
@@ -119,6 +133,19 @@ class PollVoteEvent extends PollEvent {
   Map<String, dynamic> toJson() => _$PollVoteEventToJson(this);
 }
 
+@JsonEnum(valueField: 'apiValue')
+enum VoteOp {
+  add(apiValue: 1),
+  remove(apiValue: -1),
+  unknown(apiValue: null);
+
+  const VoteOp({required this.apiValue});
+
+  final int? apiValue;
+
+  int? toJson() => apiValue;
+}
+
 class UnknownPollEvent extends PollEvent {
   @override
   @JsonKey(includeToJson: true)