Optional variables in requests

[gmb15551]

I studied the file td_api.tl. I discovered several issues with the file format.

When describing the variables of functions, it's not always clear which ones are mandatory and which ones are optional. In some cases, the annotation "pass null" is used for a variable, which likely indicates that this variable can be considered optional. However, for some optional variables, this phrase is not mentioned. For example, take the getChatHistory function. The request works fine without specifying from_message_id, offset, or only_local. But from the function description, it is unclear exactly which variables are optional. It's also not clear whether default values are used for any of these variables.

As for types, it seems somewhat clearer, as comments like "may be null" are provided. However, I'm not sure whether this covers all cases where a variable can be null.

Could you generate a new version of td_api, where the optionality of variables in the request is clearly marked in a consistent manner? Additionally, default values or flags indicating their absence should also be specified.

This would significantly simplify working with the library, as the user would be able to understand directly from the function code which data must be provided, which is optional, and what default values are applied to optional variables.

Here’s an example of a function that is currently generated. For optional variables, we need to indicate either "?" after the type or provide a default value. However, from the function description, there’s no clear guidance on when this can be done.

  /// Returns messages in a chat. The messages are returned in reverse
  /// chronological order (i.e., in order of decreasing message_id). For optimal
  /// performance, the number of returned messages is chosen by TDLib. This is
  /// an offline request if only_local is true
  ///
  /// [chat_id]
  /// Chat identifier
  ///
  /// [from_message_id]
  /// Identifier of the message starting from which history must be fetched; use
  /// 0 to get results from the last message
  ///
  /// [limit]
  /// The maximum number of messages to be returned; must be positive and can't
  /// be greater than 100. If the offset is negative, the limit must be greater
  /// than or equal to -offset. For optimal performance, the number of returned
  /// messages is chosen by TDLib and can be smaller than the specified limit
  ///
  /// [offset]
  /// Specify 0 to get results from exactly the message from_message_id or a
  /// negative offset up to 99 to get additionally some newer messages
  ///
  /// [only_local]
  /// Pass true to get only messages that are available without sending network
  /// requests
  Future<Messages> getChatHistory({
    required Int53 chat_id,
    required Int53 from_message_id,
    required Int32 limit,
    required Int32 offset,
    required bool only_local,
  }) async {
    return await sendRequest({
      '@type': 'getChatHistory',
      'chat_id': chat_id,
      'from_message_id': from_message_id,
      'limit': limit,
      'offset': offset,
      'only_local': only_local,
    }) as Messages;
  }

[levlam]

There are no optional parameters in the requests. The mentoned from_message_id, offset, and only_local parameters are required, despite rarely default values will fit. if a parameter is omitted in JSON interface, then it will have default value, which is false/0/empty string/empty array/null. If passing null as the value of a parameter has special meaning, then this is always documented.