From 1f1d97f1e310f75af00438576a21abaf2d3a2e13 Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 15:44:24 +0300
Subject: [PATCH 01/11] Add sticker and sticker set type documentation

---
 types.go | 103 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 74 insertions(+), 29 deletions(-)

diff --git a/types.go b/types.go
index 8c907f0..f5390b5 100644
--- a/types.go
+++ b/types.go
@@ -428,51 +428,96 @@ func (e MessageEntity) IsTextLink() bool {
 
 // PhotoSize contains information about photos.
 type PhotoSize struct {
-	FileID   string `json:"file_id"`
-	Width    int    `json:"width"`
-	Height   int    `json:"height"`
-	FileSize int    `json:"file_size"` // optional
+	// FileID identifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// Width photo width
+	Width int `json:"width"`
+	// Height photo height
+	Height int `json:"height"`
+	// FileSize file size
+	// optional
+	FileSize int `json:"file_size"`
 }
 
 // Audio contains information about audio.
 type Audio struct {
-	FileID    string `json:"file_id"`
-	Duration  int    `json:"duration"`
-	Performer string `json:"performer"` // optional
-	Title     string `json:"title"`     // optional
-	MimeType  string `json:"mime_type"` // optional
-	FileSize  int    `json:"file_size"` // optional
+	// FileID is an identifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// Duration of the audio in seconds as defined by sender
+	Duration int `json:"duration"`
+	// Performer of the audio as defined by sender or by audio tags
+	// optional
+	Performer string `json:"performer"`
+	// Title of the audio as defined by sender or by audio tags
+	// optional
+	Title string `json:"title"`
+	// MimeType of the file as defined by sender
+	// optional
+	MimeType string `json:"mime_type"`
+	// FileSize file size
+	// optional
+	FileSize int `json:"file_size"`
 }
 
 // Document contains information about a document.
 type Document struct {
-	FileID    string     `json:"file_id"`
-	Thumbnail *PhotoSize `json:"thumb"`     // optional
-	FileName  string     `json:"file_name"` // optional
-	MimeType  string     `json:"mime_type"` // optional
-	FileSize  int        `json:"file_size"` // optional
+	// FileID is a identifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// Thumbnail document thumbnail as defined by sender
+	// optional
+	Thumbnail *PhotoSize `json:"thumb"`
+	// FileName original filename as defined by sender
+	// optional
+	FileName string `json:"file_name"`
+	// MimeType  of the file as defined by sender
+	// optional
+	MimeType string `json:"mime_type"`
+	// FileSize file size
+	// optional
+	FileSize int `json:"file_size"`
 }
 
 // Sticker contains information about a sticker.
 type Sticker struct {
-	FileUniqueID string     `json:"file_unique_id"`
-	FileID       string     `json:"file_id"`
-	Width        int        `json:"width"`
-	Height       int        `json:"height"`
-	Thumbnail    *PhotoSize `json:"thumb"`       // optional
-	Emoji        string     `json:"emoji"`       // optional
-	FileSize     int        `json:"file_size"`   // optional
-	SetName      string     `json:"set_name"`    // optional
-	IsAnimated   bool       `json:"is_animated"` // optional
+	// FileUniqueID is an unique identifier for this file,
+	// which is supposed to be the same over time and for different bots.
+	// Can't be used to download or reuse the file.
+	FileUniqueID string `json:"file_unique_id"`
+	// FileID is an identifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// Width sticker width
+	Width int `json:"width"`
+	// Height sticker height
+	Height int `json:"height"`
+	// Thumbnail sticker thumbnail in the .WEBP or .JPG format
+	// optional
+	Thumbnail *PhotoSize `json:"thumb"`
+	// Emoji associated with the sticker
+	// optional
+	Emoji string `json:"emoji"`
+	// FileSize
+	// optional
+	FileSize int `json:"file_size"`
+	// SetName of the sticker set to which the sticker belongs
+	// optional
+	SetName string `json:"set_name"`
+	// IsAnimated true, if the sticker is animated
+	// optional
+	IsAnimated bool `json:"is_animated"`
 }
 
 // StickerSet contains information about an sticker set.
 type StickerSet struct {
-	Name          string    `json:"name"`
-	Title         string    `json:"title"`
-	IsAnimated    bool      `json:"is_animated"`
-	ContainsMasks bool      `json:"contains_masks"`
-	Stickers      []Sticker `json:"stickers"`
+	// Name sticker set name
+	Name string `json:"name"`
+	// Title sticker set title
+	Title string `json:"title"`
+	// IsAnimated true, if the sticker set contains animated stickers
+	IsAnimated bool `json:"is_animated"`
+	// ContainsMasks true, if the sticker set contains masks
+	ContainsMasks bool `json:"contains_masks"`
+	// Stickers list of all set stickers
+	Stickers []Sticker `json:"stickers"`
 }
 
 // ChatAnimation contains information about an animation.

From a005cff757a80dcb6ce777ca32b6308a02124c90 Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 16:21:42 +0300
Subject: [PATCH 02/11] Add chat animation type documentation

---
 types.go | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/types.go b/types.go
index f5390b5..888f97a 100644
--- a/types.go
+++ b/types.go
@@ -522,14 +522,26 @@ type StickerSet struct {
 
 // ChatAnimation contains information about an animation.
 type ChatAnimation struct {
-	FileID    string     `json:"file_id"`
-	Width     int        `json:"width"`
-	Height    int        `json:"height"`
-	Duration  int        `json:"duration"`
-	Thumbnail *PhotoSize `json:"thumb"`     // optional
-	FileName  string     `json:"file_name"` // optional
-	MimeType  string     `json:"mime_type"` // optional
-	FileSize  int        `json:"file_size"` // optional
+	// FileID odentifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// Width video width as defined by sender
+	Width int `json:"width"`
+	// Height video height as defined by sender
+	Height int `json:"height"`
+	// Duration of the video in seconds as defined by sender
+	Duration int `json:"duration"`
+	// Thumbnail animation thumbnail as defined by sender
+	// optional
+	Thumbnail *PhotoSize `json:"thumb"`
+	// FileName original animation filename as defined by sender
+	// optional
+	FileName string `json:"file_name"`
+	// MimeType of the file as defined by sender
+	// optional
+	MimeType string `json:"mime_type"`
+	// FileSize file size
+	// optional
+	FileSize int `json:"file_size"`
 }
 
 // Video contains information about a video.

From 8e875a571162163512ed376fe0e0a8dc4c0a3354 Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 16:25:05 +0300
Subject: [PATCH 03/11] Add video and video note type documentation

---
 types.go | 41 +++++++++++++++++++++++++++++------------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/types.go b/types.go
index 888f97a..1f3a02b 100644
--- a/types.go
+++ b/types.go
@@ -546,22 +546,39 @@ type ChatAnimation struct {
 
 // Video contains information about a video.
 type Video struct {
-	FileID    string     `json:"file_id"`
-	Width     int        `json:"width"`
-	Height    int        `json:"height"`
-	Duration  int        `json:"duration"`
-	Thumbnail *PhotoSize `json:"thumb"`     // optional
-	MimeType  string     `json:"mime_type"` // optional
-	FileSize  int        `json:"file_size"` // optional
+	// FileID identifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// Width video width as defined by sender
+	Width int `json:"width"`
+	// Height video height as defined by sender
+	Height int `json:"height"`
+	// Duration of the video in seconds as defined by sender
+	Duration int `json:"duration"`
+	// Thumbnail video thumbnail
+	// optional
+	Thumbnail *PhotoSize `json:"thumb"`
+	// MimeType of a file as defined by sender
+	// optional
+	MimeType string `json:"mime_type"`
+	// FileSize file size
+	// optional
+	FileSize int `json:"file_size"`
 }
 
 // VideoNote contains information about a video.
 type VideoNote struct {
-	FileID    string     `json:"file_id"`
-	Length    int        `json:"length"`
-	Duration  int        `json:"duration"`
-	Thumbnail *PhotoSize `json:"thumb"`     // optional
-	FileSize  int        `json:"file_size"` // optional
+	// FileID identifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// Length video width and height (diameter of the video message) as defined by sender
+	Length int `json:"length"`
+	// Duration of the video in seconds as defined by sender
+	Duration int `json:"duration"`
+	// Thumbnail video thumbnail
+	// optional
+	Thumbnail *PhotoSize `json:"thumb"`
+	// FileSize file size
+	// optional
+	FileSize int `json:"file_size"`
 }
 
 // Voice contains information about a voice.

From 1b845170c17a2379a5dc5d30e216e220789b1061 Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 16:28:10 +0300
Subject: [PATCH 04/11] Add voice and contact type documentation

---
 types.go | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/types.go b/types.go
index 1f3a02b..50c1425 100644
--- a/types.go
+++ b/types.go
@@ -583,20 +583,32 @@ type VideoNote struct {
 
 // Voice contains information about a voice.
 type Voice struct {
-	FileID   string `json:"file_id"`
-	Duration int    `json:"duration"`
-	MimeType string `json:"mime_type"` // optional
-	FileSize int    `json:"file_size"` // optional
+	// FileID identifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// Duration of the audio in seconds as defined by sender
+	Duration int `json:"duration"`
+	// MimeType of the file as defined by sender
+	// optional
+	MimeType string `json:"mime_type"`
+	// FileSize file size
+	// optional
+	FileSize int `json:"file_size"`
 }
 
 // Contact contains information about a contact.
 //
 // Note that LastName and UserID may be empty.
 type Contact struct {
+	// PhoneNumber contact's phone number
 	PhoneNumber string `json:"phone_number"`
-	FirstName   string `json:"first_name"`
-	LastName    string `json:"last_name"` // optional
-	UserID      int    `json:"user_id"`   // optional
+	// FirstName contact's first name
+	FirstName string `json:"first_name"`
+	// LastName contact's last name
+	// optional
+	LastName string `json:"last_name"`
+	// UserID contact's user identifier in Telegram
+	// optional
+	UserID int `json:"user_id"`
 }
 
 // Location contains information about a place.

From 2497684181e131be5616e36bf9cdc6d3da7db290 Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 16:30:45 +0300
Subject: [PATCH 05/11] Add location, venue and user profile photos type
 documentation

---
 types.go | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/types.go b/types.go
index 50c1425..0698d40 100644
--- a/types.go
+++ b/types.go
@@ -613,22 +613,31 @@ type Contact struct {
 
 // Location contains information about a place.
 type Location struct {
+	// Longitude as defined by sender
 	Longitude float64 `json:"longitude"`
-	Latitude  float64 `json:"latitude"`
+	// Latitude as defined by sender
+	Latitude float64 `json:"latitude"`
 }
 
 // Venue contains information about a venue, including its Location.
 type Venue struct {
-	Location     Location `json:"location"`
-	Title        string   `json:"title"`
-	Address      string   `json:"address"`
-	FoursquareID string   `json:"foursquare_id"` // optional
+	// Location venue location
+	Location Location `json:"location"`
+	// Title name of the venue
+	Title string `json:"title"`
+	// Address of the venue
+	Address string `json:"address"`
+	// FoursquareID foursquare identifier of the venue
+	// optional
+	FoursquareID string `json:"foursquare_id"`
 }
 
 // UserProfilePhotos contains a set of user profile photos.
 type UserProfilePhotos struct {
-	TotalCount int           `json:"total_count"`
-	Photos     [][]PhotoSize `json:"photos"`
+	// TotalCount total number of profile pictures the target user has
+	TotalCount int `json:"total_count"`
+	// Photos requested profile pictures (in up to 4 sizes each)
+	Photos [][]PhotoSize `json:"photos"`
 }
 
 // File contains information about a file to download from Telegram.

From bf143a9e9ba8a9e9e6265acc862c1f54fe1d87b7 Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 16:47:12 +0300
Subject: [PATCH 06/11] Add keyboard types documentation

---
 types.go | 195 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 177 insertions(+), 18 deletions(-)

diff --git a/types.go b/types.go
index 0698d40..73c93ed 100644
--- a/types.go
+++ b/types.go
@@ -137,6 +137,7 @@ type Message struct {
 	// MessageID is a unique message identifier inside this chat
 	MessageID int `json:"message_id"`
 	// From is a sender, empty for messages sent to channels;
+	//
 	// optional
 	From *User `json:"from"`
 	// Date of the message was sent in Unix time
@@ -144,105 +145,136 @@ type Message struct {
 	// Chat is the conversation the message belongs to
 	Chat *Chat `json:"chat"`
 	// ForwardFrom for forwarded messages, sender of the original message;
+	//
 	// optional
 	ForwardFrom *User `json:"forward_from"`
 	// ForwardFromChat for messages forwarded from channels,
 	// information about the original channel;
+	//
 	// optional
 	ForwardFromChat *Chat `json:"forward_from_chat"`
 	// ForwardFromMessageID for messages forwarded from channels,
 	// identifier of the original message in the channel;
+	//
 	// optional
 	ForwardFromMessageID int `json:"forward_from_message_id"`
 	// ForwardDate for forwarded messages, date the original message was sent in Unix time;
+	//
 	// optional
 	ForwardDate int `json:"forward_date"`
 	// ReplyToMessage for replies, the original message.
 	// Note that the Message object in this field will not contain further ReplyToMessage fields
 	// even if it itself is a reply;
+	//
 	// optional
 	ReplyToMessage *Message `json:"reply_to_message"`
 	// ViaBot through which the message was sent;
+	//
 	// optional
 	ViaBot *User `json:"via_bot"`
 	// EditDate of the message was last edited in Unix time;
+	//
 	// optional
 	EditDate int `json:"edit_date"`
 	// MediaGroupID is the unique identifier of a media message group this message belongs to;
+	//
 	// optional
 	MediaGroupID string `json:"media_group_id"`
 	// AuthorSignature is the signature of the post author for messages in channels;
+	//
 	// optional
 	AuthorSignature string `json:"author_signature"`
 	// Text is for text messages, the actual UTF-8 text of the message, 0-4096 characters;
+	//
 	// optional
 	Text string `json:"text"`
 	// Entities is for text messages, special entities like usernames,
 	// URLs, bot commands, etc. that appear in the text;
+	//
 	// optional
 	Entities *[]MessageEntity `json:"entities"`
 	// CaptionEntities;
+	//
 	// optional
 	CaptionEntities *[]MessageEntity `json:"caption_entities"`
 	// Audio message is an audio file, information about the file;
+	//
 	// optional
 	Audio *Audio `json:"audio"`
 	// Document message is a general file, information about the file;
+	//
 	// optional
 	Document *Document `json:"document"`
 	// Animation message is an animation, information about the animation.
 	// For backward compatibility, when this field is set, the document field will also be set;
+	//
 	// optional
 	Animation *ChatAnimation `json:"animation"`
 	// Game message is a game, information about the game;
+	//
 	// optional
 	Game *Game `json:"game"`
 	// Photo message is a photo, available sizes of the photo;
+	//
 	// optional
 	Photo *[]PhotoSize `json:"photo"`
 	// Sticker message is a sticker, information about the sticker;
+	//
 	// optional
 	Sticker *Sticker `json:"sticker"`
 	// Video message is a video, information about the video;
+	//
 	// optional
 	Video *Video `json:"video"`
 	// VideoNote message is a video note, information about the video message;
+	//
 	// optional
 	VideoNote *VideoNote `json:"video_note"`
 	// Voice message is a voice message, information about the file;
+	//
 	// optional
 	Voice *Voice `json:"voice"`
 	// Caption for the animation, audio, document, photo, video or voice, 0-1024 characters;
+	//
 	// optional
 	Caption string `json:"caption"`
 	// Contact message is a shared contact, information about the contact;
+	//
 	// optional
 	Contact *Contact `json:"contact"`
 	// Location message is a shared location, information about the location;
+	//
 	// optional
 	Location *Location `json:"location"`
 	// Venue message is a venue, information about the venue.
 	// For backward compatibility, when this field is set, the location field will also be set;
+	//
 	// optional
 	Venue *Venue `json:"venue"`
 	// NewChatMembers that were added to the group or supergroup
 	// and information about them (the bot itself may be one of these members);
+	//
 	// optional
 	NewChatMembers *[]User `json:"new_chat_members"`
 	// LeftChatMember is a member was removed from the group,
 	// information about them (this member may be the bot itself);
+	//
 	// optional
 	LeftChatMember *User `json:"left_chat_member"`
 	// NewChatTitle is a chat title was changed to this value;
+	//
 	// optional
 	NewChatTitle string `json:"new_chat_title"`
 	// NewChatPhoto is a chat photo was change to this value;
+	//
 	// optional
 	NewChatPhoto *[]PhotoSize `json:"new_chat_photo"`
 	// DeleteChatPhoto is a service message: the chat photo was deleted;
+	//
 	// optional
 	DeleteChatPhoto bool `json:"delete_chat_photo"`
 	// GroupChatCreated is a service message: the group has been created;
+	//
 	// optional
 	GroupChatCreated bool `json:"group_chat_created"`
 	// SuperGroupChatCreated is a service message: the supergroup has been created.
@@ -250,6 +282,7 @@ type Message struct {
 	// because bot can't be a member of a supergroup when it is created.
 	// It can only be found in ReplyToMessage if someone replies to a very first message
 	// in a directly created supergroup;
+	//
 	// optional
 	SuperGroupChatCreated bool `json:"supergroup_chat_created"`
 	// ChannelChatCreated is a service message: the channel has been created.
@@ -257,6 +290,7 @@ type Message struct {
 	// because bot can't be a member of a channel when it is created.
 	// It can only be found in ReplyToMessage
 	// if someone replies to a very first message in a channel;
+	//
 	// optional
 	ChannelChatCreated bool `json:"channel_chat_created"`
 	// MigrateToChatID is the group has been migrated to a supergroup with the specified identifier.
@@ -264,6 +298,7 @@ type Message struct {
 	// may have difficulty/silent defects in interpreting it.
 	// But it is smaller than 52 bits, so a signed 64 bit integer
 	// or double-precision float type are safe for storing this identifier;
+	//
 	// optional
 	MigrateToChatID int64 `json:"migrate_to_chat_id"`
 	// MigrateFromChatID is the supergroup has been migrated from a group with the specified identifier.
@@ -271,21 +306,26 @@ type Message struct {
 	// may have difficulty/silent defects in interpreting it.
 	// But it is smaller than 52 bits, so a signed 64 bit integer
 	// or double-precision float type are safe for storing this identifier;
+	//
 	// optional
 	MigrateFromChatID int64 `json:"migrate_from_chat_id"`
 	// PinnedMessage is a specified message was pinned.
 	// Note that the Message object in this field will not contain further ReplyToMessage
 	// fields even if it is itself a reply;
+	//
 	// optional
 	PinnedMessage *Message `json:"pinned_message"`
 	// Invoice message is an invoice for a payment;
+	//
 	// optional
 	Invoice *Invoice `json:"invoice"`
 	// SuccessfulPayment message is a service message about a successful payment,
 	// information about the payment;
+	//
 	// optional
 	SuccessfulPayment *SuccessfulPayment `json:"successful_payment"`
 	// PassportData is a Telegram Passport data;
+	//
 	// optional
 	PassportData *PassportData `json:"passport_data,omitempty"`
 }
@@ -435,6 +475,7 @@ type PhotoSize struct {
 	// Height photo height
 	Height int `json:"height"`
 	// FileSize file size
+	//
 	// optional
 	FileSize int `json:"file_size"`
 }
@@ -446,15 +487,19 @@ type Audio struct {
 	// Duration of the audio in seconds as defined by sender
 	Duration int `json:"duration"`
 	// Performer of the audio as defined by sender or by audio tags
+	//
 	// optional
 	Performer string `json:"performer"`
 	// Title of the audio as defined by sender or by audio tags
+	//
 	// optional
 	Title string `json:"title"`
 	// MimeType of the file as defined by sender
+	//
 	// optional
 	MimeType string `json:"mime_type"`
 	// FileSize file size
+	//
 	// optional
 	FileSize int `json:"file_size"`
 }
@@ -464,15 +509,19 @@ type Document struct {
 	// FileID is a identifier for this file, which can be used to download or reuse the file
 	FileID string `json:"file_id"`
 	// Thumbnail document thumbnail as defined by sender
+	//
 	// optional
 	Thumbnail *PhotoSize `json:"thumb"`
 	// FileName original filename as defined by sender
+	//
 	// optional
 	FileName string `json:"file_name"`
 	// MimeType  of the file as defined by sender
+	//
 	// optional
 	MimeType string `json:"mime_type"`
 	// FileSize file size
+	//
 	// optional
 	FileSize int `json:"file_size"`
 }
@@ -490,18 +539,23 @@ type Sticker struct {
 	// Height sticker height
 	Height int `json:"height"`
 	// Thumbnail sticker thumbnail in the .WEBP or .JPG format
+	//
 	// optional
 	Thumbnail *PhotoSize `json:"thumb"`
 	// Emoji associated with the sticker
+	//
 	// optional
 	Emoji string `json:"emoji"`
 	// FileSize
+	//
 	// optional
 	FileSize int `json:"file_size"`
 	// SetName of the sticker set to which the sticker belongs
+	//
 	// optional
 	SetName string `json:"set_name"`
 	// IsAnimated true, if the sticker is animated
+	//
 	// optional
 	IsAnimated bool `json:"is_animated"`
 }
@@ -531,15 +585,19 @@ type ChatAnimation struct {
 	// Duration of the video in seconds as defined by sender
 	Duration int `json:"duration"`
 	// Thumbnail animation thumbnail as defined by sender
+	//
 	// optional
 	Thumbnail *PhotoSize `json:"thumb"`
 	// FileName original animation filename as defined by sender
+	//
 	// optional
 	FileName string `json:"file_name"`
 	// MimeType of the file as defined by sender
+	//
 	// optional
 	MimeType string `json:"mime_type"`
 	// FileSize file size
+	//
 	// optional
 	FileSize int `json:"file_size"`
 }
@@ -555,12 +613,15 @@ type Video struct {
 	// Duration of the video in seconds as defined by sender
 	Duration int `json:"duration"`
 	// Thumbnail video thumbnail
+	//
 	// optional
 	Thumbnail *PhotoSize `json:"thumb"`
 	// MimeType of a file as defined by sender
+	//
 	// optional
 	MimeType string `json:"mime_type"`
 	// FileSize file size
+	//
 	// optional
 	FileSize int `json:"file_size"`
 }
@@ -574,9 +635,11 @@ type VideoNote struct {
 	// Duration of the video in seconds as defined by sender
 	Duration int `json:"duration"`
 	// Thumbnail video thumbnail
+	//
 	// optional
 	Thumbnail *PhotoSize `json:"thumb"`
 	// FileSize file size
+	//
 	// optional
 	FileSize int `json:"file_size"`
 }
@@ -588,9 +651,11 @@ type Voice struct {
 	// Duration of the audio in seconds as defined by sender
 	Duration int `json:"duration"`
 	// MimeType of the file as defined by sender
+	//
 	// optional
 	MimeType string `json:"mime_type"`
 	// FileSize file size
+	//
 	// optional
 	FileSize int `json:"file_size"`
 }
@@ -604,9 +669,11 @@ type Contact struct {
 	// FirstName contact's first name
 	FirstName string `json:"first_name"`
 	// LastName contact's last name
+	//
 	// optional
 	LastName string `json:"last_name"`
 	// UserID contact's user identifier in Telegram
+	//
 	// optional
 	UserID int `json:"user_id"`
 }
@@ -628,6 +695,7 @@ type Venue struct {
 	// Address of the venue
 	Address string `json:"address"`
 	// FoursquareID foursquare identifier of the venue
+	//
 	// optional
 	FoursquareID string `json:"foursquare_id"`
 }
@@ -642,9 +710,16 @@ type UserProfilePhotos struct {
 
 // File contains information about a file to download from Telegram.
 type File struct {
-	FileID   string `json:"file_id"`
-	FileSize int    `json:"file_size"` // optional
-	FilePath string `json:"file_path"` // optional
+	// FileID identifier for this file, which can be used to download or reuse the file
+	FileID string `json:"file_id"`
+	// FileSize file size, if known
+	//
+	// optional
+	FileSize int `json:"file_size"`
+	// FilePath file path
+	//
+	// optional
+	FilePath string `json:"file_path"`
 }
 
 // Link returns a full path to the download URL for a File.
@@ -656,17 +731,52 @@ func (f *File) Link(token string) string {
 
 // ReplyKeyboardMarkup allows the Bot to set a custom keyboard.
 type ReplyKeyboardMarkup struct {
-	Keyboard        [][]KeyboardButton `json:"keyboard"`
-	ResizeKeyboard  bool               `json:"resize_keyboard"`   // optional
-	OneTimeKeyboard bool               `json:"one_time_keyboard"` // optional
-	Selective       bool               `json:"selective"`         // optional
+	// Keyboard is an array of button rows, each represented by an Array of KeyboardButton objects
+	Keyboard [][]KeyboardButton `json:"keyboard"`
+	// ResizeKeyboard requests clients to resize the keyboard vertically for optimal fit
+	// (e.g., make the keyboard smaller if there are just two rows of buttons).
+	// Defaults to false, in which case the custom keyboard
+	// is always of the same height as the app's standard keyboard.
+	//
+	// optional
+	ResizeKeyboard bool `json:"resize_keyboard"`
+	// OneTimeKeyboard requests clients to hide the keyboard as soon as it's been used.
+	// The keyboard will still be available, but clients will automatically display
+	// the usual letter-keyboard in the chat – the user can press a special button
+	// in the input field to see the custom keyboard again.
+	// Defaults to false.
+	//
+	// optional
+	OneTimeKeyboard bool `json:"one_time_keyboard"`
+	// Selective use this parameter if you want to show the keyboard to specific users only.
+	// Targets:
+	//  1) users that are @mentioned in the text of the Message object;
+	//  2) if the bot's message is a reply (has Message.ReplyToMessage not nil), sender of the original message.
+	//
+	// Example: A user requests to change the bot's language,
+	// bot replies to the request with a keyboard to select the new language.
+	// Other users in the group don't see the keyboard.
+	//
+	// optional
+	Selective bool `json:"selective"`
 }
 
 // KeyboardButton is a button within a custom keyboard.
 type KeyboardButton struct {
-	Text            string `json:"text"`
-	RequestContact  bool   `json:"request_contact"`
-	RequestLocation bool   `json:"request_location"`
+	// Text of the button. If none of the optional fields are used,
+	// it will be sent as a message when the button is pressed.
+	Text string `json:"text"`
+	// RequestContact if True, the user's phone number will be sent
+	// as a contact when the button is pressed.
+	// Available in private chats only.
+	//
+	// optional
+	RequestContact bool `json:"request_contact"`
+	// RequestLocation if True, the user's current location will be sent when the button is pressed.
+	// Available in private chats only.
+	//
+	// optional
+	RequestLocation bool `json:"request_location"`
 }
 
 // ReplyKeyboardHide allows the Bot to hide a custom keyboard.
@@ -677,12 +787,27 @@ type ReplyKeyboardHide struct {
 
 // ReplyKeyboardRemove allows the Bot to hide a custom keyboard.
 type ReplyKeyboardRemove struct {
+	// RemoveKeyboard requests clients to remove the custom keyboard
+	// (user will not be able to summon this keyboard;
+	// if you want to hide the keyboard from sight but keep it accessible,
+	// use one_time_keyboard in ReplyKeyboardMarkup).
 	RemoveKeyboard bool `json:"remove_keyboard"`
-	Selective      bool `json:"selective"`
+	// Selective use this parameter if you want to remove the keyboard for specific users only.
+	// Targets:
+	//  1) users that are @mentioned in the text of the Message object;
+	//  2) if the bot's message is a reply (has Message.ReplyToMessage not nil), sender of the original message.
+	//
+	// Example: A user votes in a poll, bot returns confirmation message
+	// in reply to the vote and removes the keyboard for that user,
+	// while still showing the keyboard with poll options to users who haven't voted yet.
+	//
+	// optional
+	Selective bool `json:"selective"`
 }
 
 // InlineKeyboardMarkup is a custom keyboard presented for an inline bot.
 type InlineKeyboardMarkup struct {
+	// InlineKeyboard array of button rows, each represented by an Array of InlineKeyboardButton objects
 	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
 }
 
@@ -694,13 +819,47 @@ type InlineKeyboardMarkup struct {
 //
 // CallbackGame, if set, MUST be first button in first row.
 type InlineKeyboardButton struct {
-	Text                         string        `json:"text"`
-	URL                          *string       `json:"url,omitempty"`                              // optional
-	CallbackData                 *string       `json:"callback_data,omitempty"`                    // optional
-	SwitchInlineQuery            *string       `json:"switch_inline_query,omitempty"`              // optional
-	SwitchInlineQueryCurrentChat *string       `json:"switch_inline_query_current_chat,omitempty"` // optional
-	CallbackGame                 *CallbackGame `json:"callback_game,omitempty"`                    // optional
-	Pay                          bool          `json:"pay,omitempty"`                              // optional
+	// Text label text on the button
+	Text string `json:"text"`
+	// URL HTTP or tg:// url to be opened when button is pressed.
+	//
+	// optional
+	URL *string `json:"url,omitempty"`
+	// CallbackData data to be sent in a callback query to the bot when button is pressed, 1-64 bytes.
+	//
+	// optional
+	CallbackData *string `json:"callback_data,omitempty"`
+	// SwitchInlineQuery if set, pressing the button will prompt the user to select one of their chats,
+	// open that chat and insert the bot's username and the specified inline query in the input field.
+	// Can be empty, in which case just the bot's username will be inserted.
+	//
+	// This offers an easy way for users to start using your bot
+	// in inline mode when they are currently in a private chat with it.
+	// Especially useful when combined with switch_pm… actions – in this case
+	// the user will be automatically returned to the chat they switched from,
+	// skipping the chat selection screen.
+	//
+	// optional
+	SwitchInlineQuery *string `json:"switch_inline_query,omitempty"`
+	// SwitchInlineQueryCurrentChat if set, pressing the button will insert the bot's username
+	// and the specified inline query in the current chat's input field.
+	// Can be empty, in which case only the bot's username will be inserted.
+	//
+	// This offers a quick way for the user to open your bot in inline mode
+	// in the same chat – good for selecting something from multiple options.
+	//
+	// optional
+	SwitchInlineQueryCurrentChat *string `json:"switch_inline_query_current_chat,omitempty"`
+	// CallbackGame description of the game that will be launched when the user presses the button.
+	//
+	// optional
+	CallbackGame *CallbackGame `json:"callback_game,omitempty"`
+	// Pay specify True, to send a Pay button.
+	//
+	// NOTE: This type of button must always be the first button in the first row.
+	//
+	// optional
+	Pay bool `json:"pay,omitempty"`
 }
 
 // CallbackQuery is data sent when a keyboard button with callback data

From f54e99475aeeb0729f8e3212116e2f9bb3bc0bd5 Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 16:52:22 +0300
Subject: [PATCH 07/11] Add callback and reply types documentation

---
 types.go | 44 ++++++++++++++++++++++++++++++++++++--------
 1 file changed, 36 insertions(+), 8 deletions(-)

diff --git a/types.go b/types.go
index 73c93ed..e697217 100644
--- a/types.go
+++ b/types.go
@@ -865,20 +865,48 @@ type InlineKeyboardButton struct {
 // CallbackQuery is data sent when a keyboard button with callback data
 // is clicked.
 type CallbackQuery struct {
-	ID              string   `json:"id"`
-	From            *User    `json:"from"`
-	Message         *Message `json:"message"`           // optional
-	InlineMessageID string   `json:"inline_message_id"` // optional
-	ChatInstance    string   `json:"chat_instance"`
-	Data            string   `json:"data"`            // optional
-	GameShortName   string   `json:"game_short_name"` // optional
+	// ID unique identifier for this query
+	ID string `json:"id"`
+	// From sender
+	From *User `json:"from"`
+	// Message with the callback button that originated the query.
+	// Note that message content and message date will not be available if the message is too old.
+	//
+	// optional
+	Message *Message `json:"message"`
+	// InlineMessageID identifier of the message sent via the bot in inline mode, that originated the query.
+	//
+	// optional
+	//
+	InlineMessageID string `json:"inline_message_id"`
+	// ChatInstance global identifier, uniquely corresponding to the chat to which
+	// the message with the callback button was sent. Useful for high scores in games.
+	//
+	ChatInstance string `json:"chat_instance"`
+	// Data associated with the callback button. Be aware that
+	// a bad client can send arbitrary data in this field.
+	//
+	// optional
+	Data string `json:"data"`
+	// GameShortName short name of a Game to be returned, serves as the unique identifier for the game.
+	//
+	// optional
+	GameShortName string `json:"game_short_name"`
 }
 
 // ForceReply allows the Bot to have users directly reply to it without
 // additional interaction.
 type ForceReply struct {
+	// ForceReply shows reply interface to the user,
+	// as if they manually selected the bot's message and tapped 'Reply'.
 	ForceReply bool `json:"force_reply"`
-	Selective  bool `json:"selective"` // optional
+	// Selective use this parameter if you want to force reply from specific users only.
+	// Targets:
+	//  1) users that are @mentioned in the text of the Message object;
+	//  2) if the bot's message is a reply (has Message.ReplyToMessage not nil), sender of the original message.
+	//
+	// optional
+	Selective bool `json:"selective"`
 }
 
 // ChatMember is information about a member in a chat.

From d2ea97fb9b113760160c321b738352efa85e0f6e Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 16:58:02 +0300
Subject: [PATCH 08/11] Add chat member type documentation

---
 types.go | 106 ++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 89 insertions(+), 17 deletions(-)

diff --git a/types.go b/types.go
index e697217..b252c47 100644
--- a/types.go
+++ b/types.go
@@ -911,23 +911,95 @@ type ForceReply struct {
 
 // ChatMember is information about a member in a chat.
 type ChatMember struct {
-	User                  *User  `json:"user"`
-	Status                string `json:"status"`
-	CustomTitle           string `json:"custom_title,omitempty"`              // optional
-	UntilDate             int64  `json:"until_date,omitempty"`                // optional
-	CanBeEdited           bool   `json:"can_be_edited,omitempty"`             // optional
-	CanChangeInfo         bool   `json:"can_change_info,omitempty"`           // optional
-	CanPostMessages       bool   `json:"can_post_messages,omitempty"`         // optional
-	CanEditMessages       bool   `json:"can_edit_messages,omitempty"`         // optional
-	CanDeleteMessages     bool   `json:"can_delete_messages,omitempty"`       // optional
-	CanInviteUsers        bool   `json:"can_invite_users,omitempty"`          // optional
-	CanRestrictMembers    bool   `json:"can_restrict_members,omitempty"`      // optional
-	CanPinMessages        bool   `json:"can_pin_messages,omitempty"`          // optional
-	CanPromoteMembers     bool   `json:"can_promote_members,omitempty"`       // optional
-	CanSendMessages       bool   `json:"can_send_messages,omitempty"`         // optional
-	CanSendMediaMessages  bool   `json:"can_send_media_messages,omitempty"`   // optional
-	CanSendOtherMessages  bool   `json:"can_send_other_messages,omitempty"`   // optional
-	CanAddWebPagePreviews bool   `json:"can_add_web_page_previews,omitempty"` // optional
+	// User information about the user
+	User *User `json:"user"`
+	// Status the member's status in the chat.
+	// Can be
+	//  “creator”,
+	//  “administrator”,
+	//  “member”,
+	//  “restricted”,
+	//  “left” or
+	//  “kicked”
+	Status string `json:"status"`
+	// CustomTitle owner and administrators only. Custom title for this user
+	//
+	// optional
+	CustomTitle string `json:"custom_title,omitempty"`
+	// UntilDate restricted and kicked only.
+	// Date when restrictions will be lifted for this user;
+	// unix time.
+	//
+	// optional
+	UntilDate int64 `json:"until_date,omitempty"`
+	// CanBeEdited administrators only.
+	// True, if the bot is allowed to edit administrator privileges of that user.
+	//
+	// optional
+	CanBeEdited bool `json:"can_be_edited,omitempty"`
+	// CanChangeInfo administrators and restricted only.
+	// True, if the user is allowed to change the chat title, photo and other settings.
+	//
+	// optional
+	CanChangeInfo bool `json:"can_change_info,omitempty"`
+	// CanChangeInfo administrators only.
+	// True, if the administrator can post in the channel;
+	// channels only.
+	//
+	// optional
+	CanPostMessages bool `json:"can_post_messages,omitempty"`
+	// CanEditMessages administrators only.
+	// True, if the administrator can edit messages of other users and can pin messages;
+	// channels only.
+	//
+	// optional
+	CanEditMessages bool `json:"can_edit_messages,omitempty"`
+	// CanDeleteMessages administrators only.
+	// True, if the administrator can delete messages of other users.
+	//
+	// optional
+	CanDeleteMessages bool `json:"can_delete_messages,omitempty"`
+	// CanInviteUsers administrators and restricted only.
+	// True, if the user is allowed to invite new users to the chat.
+	//
+	// optional
+	CanInviteUsers bool `json:"can_invite_users,omitempty"`
+	// CanRestrictMembers administrators only.
+	// True, if the administrator can restrict, ban or unban chat members.
+	//
+	// optional
+	CanRestrictMembers bool `json:"can_restrict_members,omitempty"`
+	// CanPinMessages
+	//
+	// optional
+	CanPinMessages bool `json:"can_pin_messages,omitempty"`
+	// CanPromoteMembers administrators only.
+	// True, if the administrator can add new administrators
+	// with a subset of their own privileges or demote administrators that he has promoted,
+	// directly or indirectly (promoted by administrators that were appointed by the user).
+	//
+	// optional
+	CanPromoteMembers bool `json:"can_promote_members,omitempty"`
+	// CanSendMessages
+	//
+	// optional
+	CanSendMessages bool `json:"can_send_messages,omitempty"`
+	// CanSendMediaMessages restricted only.
+	// True, if the user is allowed to send text messages, contacts, locations and venues
+	//
+	// optional
+	CanSendMediaMessages bool `json:"can_send_media_messages,omitempty"`
+	// CanSendOtherMessages restricted only.
+	// True, if the user is allowed to send audios, documents,
+	// photos, videos, video notes and voice notes.
+	//
+	// optional
+	CanSendOtherMessages bool `json:"can_send_other_messages,omitempty"`
+	// CanAddWebPagePreviews restricted only.
+	// True, if the user is allowed to add web page previews to their messages.
+	//
+	// optional
+	CanAddWebPagePreviews bool `json:"can_add_web_page_previews,omitempty"`
 }
 
 // IsCreator returns if the ChatMember was the creator of the chat.

From 5875a46cdedea21de70ec6f5b4d4825bb1fe6f6e Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 17:00:46 +0300
Subject: [PATCH 09/11] Add game type documentation

---
 types.go | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/types.go b/types.go
index b252c47..7876c1f 100644
--- a/types.go
+++ b/types.go
@@ -1019,12 +1019,27 @@ func (chat ChatMember) WasKicked() bool { return chat.Status == "kicked" }
 
 // Game is a game within Telegram.
 type Game struct {
-	Title        string          `json:"title"`
-	Description  string          `json:"description"`
-	Photo        []PhotoSize     `json:"photo"`
-	Text         string          `json:"text"`
+	// Title of the game
+	Title string `json:"title"`
+	// Description of the game
+	Description string `json:"description"`
+	// Photo that will be displayed in the game message in chats.
+	Photo []PhotoSize `json:"photo"`
+	// Text a brief description of the game or high scores included in the game message.
+	// Can be automatically edited to include current high scores for the game
+	// when the bot calls setGameScore, or manually edited using editMessageText. 0-4096 characters.
+	//
+	// optional
+	Text string `json:"text"`
+	// TextEntities special entities that appear in text, such as usernames, URLs, bot commands, etc.
+	//
+	// optional
 	TextEntities []MessageEntity `json:"text_entities"`
-	Animation    Animation       `json:"animation"`
+	// Animation animation that will be displayed in the game message in chats.
+	// Upload via BotFather (https://t.me/botfather).
+	//
+	// optional
+	Animation Animation `json:"animation"`
 }
 
 // Animation is a GIF animation demonstrating the game.

From d885b2a98311bb04422cf57042feab295554302f Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 17:05:16 +0300
Subject: [PATCH 10/11] Add animation, game score and webhook types
 documentation

---
 types.go | 59 ++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 45 insertions(+), 14 deletions(-)

diff --git a/types.go b/types.go
index 7876c1f..d80187c 100644
--- a/types.go
+++ b/types.go
@@ -1044,18 +1044,34 @@ type Game struct {
 
 // Animation is a GIF animation demonstrating the game.
 type Animation struct {
-	FileID   string    `json:"file_id"`
-	Thumb    PhotoSize `json:"thumb"`
-	FileName string    `json:"file_name"`
-	MimeType string    `json:"mime_type"`
-	FileSize int       `json:"file_size"`
+	// FileID identifier for this file, which can be used to download or reuse the file.
+	FileID string `json:"file_id"`
+	// Thumb animation thumbnail as defined by sender.
+	//
+	// optional
+	Thumb PhotoSize `json:"thumb"`
+	// FileName original animation filename as defined by sender.
+	//
+	// optional
+	FileName string `json:"file_name"`
+	// MimeType of the file as defined by sender.
+	//
+	// optional
+	MimeType string `json:"mime_type"`
+	// FileSize ile size
+	//
+	// optional
+	FileSize int `json:"file_size"`
 }
 
 // GameHighScore is a user's score and position on the leaderboard.
 type GameHighScore struct {
-	Position int  `json:"position"`
-	User     User `json:"user"`
-	Score    int  `json:"score"`
+	// Position in high score table for the game
+	Position int `json:"position"`
+	// User user
+	User User `json:"user"`
+	// Score score
+	Score int `json:"score"`
 }
 
 // CallbackGame is for starting a game in an inline keyboard button.
@@ -1063,12 +1079,27 @@ type CallbackGame struct{}
 
 // WebhookInfo is information about a currently set webhook.
 type WebhookInfo struct {
-	URL                  string `json:"url"`
-	HasCustomCertificate bool   `json:"has_custom_certificate"`
-	PendingUpdateCount   int    `json:"pending_update_count"`
-	LastErrorDate        int    `json:"last_error_date"`    // optional
-	LastErrorMessage     string `json:"last_error_message"` // optional
-	MaxConnections       int    `json:"max_connections"`    // optional
+	// URL webhook URL, may be empty if webhook is not set up.
+	URL string `json:"url"`
+	// HasCustomCertificate true, if a custom certificate was provided for webhook certificate checks.
+	HasCustomCertificate bool `json:"has_custom_certificate"`
+	// PendingUpdateCount number of updates awaiting delivery.
+	PendingUpdateCount int `json:"pending_update_count"`
+	// LastErrorDate unix time for the most recent error
+	// that happened when trying to deliver an update via webhook.
+	//
+	// optional
+	LastErrorDate int `json:"last_error_date"`
+	// LastErrorMessage error message in human-readable format for the most recent error
+	// that happened when trying to deliver an update via webhook.
+	//
+	// optional
+	LastErrorMessage string `json:"last_error_message"`
+	// MaxConnections maximum allowed number of simultaneous
+	// HTTPS connections to the webhook for update delivery.
+	//
+	// optional
+	MaxConnections int `json:"max_connections"`
 }
 
 // IsSet returns true if a webhook is currently set.

From 97c4ff439677d3d057bfa114067b93f85810b76d Mon Sep 17 00:00:00 2001
From: Ilya Kaznacheev <ilya@kaznacheev.me>
Date: Sat, 24 Oct 2020 17:12:11 +0300
Subject: [PATCH 11/11] Add input media types documentation

---
 types.go | 61 ++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 51 insertions(+), 10 deletions(-)

diff --git a/types.go b/types.go
index d80187c..e6ea20f 100644
--- a/types.go
+++ b/types.go
@@ -1109,23 +1109,64 @@ func (info WebhookInfo) IsSet() bool {
 
 // InputMediaPhoto contains a photo for displaying as part of a media group.
 type InputMediaPhoto struct {
-	Type      string `json:"type"`
-	Media     string `json:"media"`
-	Caption   string `json:"caption"`
+	// Type of the result, must be photo.
+	Type string `json:"type"`
+	// Media file to send. Pass a file_id to send a file that
+	// exists on the Telegram servers (recommended),
+	// pass an HTTP URL for Telegram to get a file from the Internet,
+	// or pass “attach://<file_attach_name>” to upload a new one
+	// using multipart/form-data under <file_attach_name> name.
+	Media string `json:"media"`
+	// Caption of the photo to be sent, 0-1024 characters after entities parsing.
+	//
+	// optional
+	Caption string `json:"caption"`
+	// ParseMode mode for parsing entities in the photo caption.
+	// See formatting options for more details
+	// (https://core.telegram.org/bots/api#formatting-options).
+	//
+	// optional
 	ParseMode string `json:"parse_mode"`
 }
 
 // InputMediaVideo contains a video for displaying as part of a media group.
 type InputMediaVideo struct {
-	Type  string `json:"type"`
+	// Type of the result, must be video.
+	Type string `json:"type"`
+	// Media file to send. Pass a file_id to send a file
+	// that exists on the Telegram servers (recommended),
+	// pass an HTTP URL for Telegram to get a file from the Internet,
+	// or pass “attach://<file_attach_name>” to upload a new one
+	// using multipart/form-data under <file_attach_name> name.
 	Media string `json:"media"`
 	// thumb intentionally missing as it is not currently compatible
-	Caption           string `json:"caption"`
-	ParseMode         string `json:"parse_mode"`
-	Width             int    `json:"width"`
-	Height            int    `json:"height"`
-	Duration          int    `json:"duration"`
-	SupportsStreaming bool   `json:"supports_streaming"`
+
+	// Caption of the video to be sent, 0-1024 characters after entities parsing.
+	//
+	// optional
+	Caption string `json:"caption"`
+	// ParseMode mode for parsing entities in the video caption.
+	// See formatting options for more details
+	// (https://core.telegram.org/bots/api#formatting-options).
+	//
+	// optional
+	ParseMode string `json:"parse_mode"`
+	// Width video width
+	//
+	// optional
+	Width int `json:"width"`
+	// Height video height
+	//
+	// optional
+	Height int `json:"height"`
+	// Duration video duration
+	//
+	// optional
+	Duration int `json:"duration"`
+	// SupportsStreaming pass True, if the uploaded video is suitable for streaming.
+	//
+	// optional
+	SupportsStreaming bool `json:"supports_streaming"`
 }
 
 // InlineQuery is a Query from Telegram for an inline request.