pb: document fields correctly

Signed-off-by: Xe Iaso <me@xeiaso.net>

2 files changed, 363 insertions, 166 deletions

diff --git a/pb/external/protofeed.proto b/pb/external/protofeed.proto
index da4f93b..2d87bb9 100644
--- a/pb/external/protofeed.proto
+++ b/pb/external/protofeed.proto
@@ -4,50 +4,157 @@ option go_package = "xeiaso.net/v4/pb/external/protofeed";
 
 import "google/protobuf/timestamp.proto";
 
+// Feed is the root of a Proto Feed document. A feed must at least contain a
+// title and items.
 message Feed {
-    string version = 1; // (required, string) is the URL of the version of the format the feed uses. This should appear at the very top, though we recognize that not all JSON generators allow for ordering.
-    string title = 2; // (required, string) is the name of the feed, which will often correspond to the name of the website (blog, for instance), though not necessarily.
-    string home_page_url = 3; // (optional but strongly recommended, string) is the URL of the resource that the feed describes. This resource may or may not actually be a “home” page, but it should be an HTML page. If a feed is published on the public web, this should be considered as required. But it may not make sense in the case of a file created on a desktop computer, when that file is not shared or is shared only privately.
-    string feed_url = 4; // (optional but strongly recommended, string) is the URL of the feed, and serves as the unique identifier for the feed. As with home_page_url, this should be considered required for feeds on the public web.
-    string description = 5; // (optional, string) provides more detail, beyond the title, on what the feed is about. A feed reader may display this text.
-    string user_comment = 6; // (optional, string) is a description of the purpose of the feed. This is for the use of people looking at the raw JSON, and should be ignored by feed readers.
-    string next_url = 7; // (optional, string) is the URL of a feed that provides the next n items, where n is determined by the publisher. This allows for pagination, but with the expectation that reader software is not required to use it and probably won’t use it very often. next_url must not be the same as feed_url, and it must not be the same as a previous next_url.
-    string icon = 8; // (optional, string) is the URL of an image for the feed suitable to be used in a source list. It should be square and relatively large — such as 512 x 512 — so that it can be scaled down and so that it can look good on retina displays. It should use transparency where appropriate, since it may be rendered on a non-white background.
-    string favicon = 9; // (optional, string) is the URL of an image for the feed suitable to be used in a source list. It should be square and relatively small, but not smaller than 64 x 64.
-    repeated Author authors = 10; // (optional, array of objects) specifies the feed authors.
-    string language = 11; // (optional, string) is the primary language for the feed.
-    bool expired = 12; // (optional, boolean) says whether or not the feed is finished — that is, whether or not it will ever update again. A feed for a temporary event, such as an instance of the Olympics, could expire. If the value is true, then it’s expired. Any other value, or the absence of expired, means the feed may continue to update.
-    repeated Item items = 13; // (required, array of objects) contains the items in the feed. This is the most important element of the feed after the version field. Each item is a story, blog post, article, photograph, video, or other thing. For example, if a feed contains a long article, a podcast episode, and a photo, those three items would be included in items.
+  // (required, string) is the name of the feed, which will often correspond to
+  // the name of the website (blog, for instance), though not necessarily.
+  string title = 2;
+  // (optional but strongly recommended, string) is the URL of the resource that
+  // the feed describes. This resource may or may not actually be a “home” page,
+  // but it should be an HTML page. If a feed is published on the public web,
+  // this should be considered as required. But it may not make sense in the
+  // case of a file created on a desktop computer, when that file is not shared
+  // or is shared only privately.
+  string home_page_url = 3;
+  // (optional but strongly recommended, string) is the URL of the feed, and
+  // serves as the unique identifier for the feed. As with home_page_url, this
+  // should be considered required for feeds on the public web.
+  string feed_url = 4;
+  // (optional, string) provides more detail, beyond the title, on what the feed
+  // is about. A feed reader may display this text.
+  string description = 5;
+  // (optional, string) is a description of the purpose of the feed. This is for
+  // the use of people looking at the raw Protobuf, and should be ignored by
+  // feed readers.
+  string user_comment = 6;
+  // (optional, string) is the URL of an image for the feed suitable to be used
+  // in a source list. It should be square and relatively large — such as 512 x
+  // 512 — so that it can be scaled down and so that it can look good on retina
+  // displays. It should use transparency where appropriate, since it may be
+  // rendered on a non-white background.
+  string icon = 7;
+  // (optional, string) is the URL of an image for the feed suitable to be used
+  // in a source list. It should be square and relatively small, but not smaller
+  // than 64 x 64.
+  string favicon = 8;
+  // (optional, array of objects) specifies the feed authors.
+  repeated Author authors = 9;
+  // (optional, string) is the primary language for the feed.
+  string language = 10;
+  // (optional, boolean) says whether or not the feed is finished — that is,
+  // whether or not it will ever update again. A feed for a temporary event,
+  // such as an instance of the Olympics, could expire. If the value is true,
+  // then it’s expired. Any other value, or the absence of expired, means the
+  // feed may continue to update.
+  bool expired = 11;
+  // (required, array of objects) contains the items in the feed. This is the
+  // most important element of the feed after the version field. Each item is a
+  // story, blog post, article, photograph, video, or other thing. For example,
+  // if a feed contains a long article, a podcast episode, and a photo, those
+  // three items would be included in items.
+  repeated Item items = 12;
 }
 
+// Author is an object representing the author of the feed or item.
 message Author {
-    string name = 1; // (optional, string) is the author’s name.
-    string url = 2; // (optional, string) is the URL of a site owned by the author. It could be a blog, micro-blog, Twitter account, and so on. Ideally the linked-to page provides a way to contact the author, but that’s not required. The URL could be a mailto: link, though we suspect that will be rare.
-    string avatar = 3; // (optional, string) is the URL for an image for the author. As with icon, it should be square and relatively large — such as 512 x 512 pixels — and should use transparency where appropriate, since it may be rendered on a non-white background.
+  // (optional, string) is the author’s name.
+  string name = 1;
+  // (optional, string) is the URL of a site owned by the author. It could be a
+  // blog, micro-blog, Twitter account, and so on. Ideally the linked-to page
+  // provides a way to contact the author, but that’s not required. The URL
+  // could be a mailto: link, though we suspect that will be rare.
+  string url = 2;
+  // (optional, string) is the URL for an image for the author. As with icon, it
+  // should be square and relatively large — such as 512 x 512 pixels — and
+  // should use transparency where appropriate, since it may be rendered on a
+  // non-white background.
+  string avatar = 3;
 }
 
+// Item is an object representing a single story, blog post, article,
+// photograph, video, or other thing within a feed.
 message Item {
-    string id = 1; // (required, string) is unique for that item for that feed over time. If an item is ever updated, the id should be unchanged. New items should never use a previously-used id. If an id is presented as a number or other type, a JSON Feed reader must coerce it to a string. Ideally, the id is the full URL of the resource described by the item, since URLs make great unique identifiers.
-    string url = 2; // (optional, string) is the URL of the resource described by the item. It’s the permalink. This may be the same as the id — but should be present regardless.
-    string external_url = 3; // (optional, string) is the URL of a page elsewhere. This is especially useful for linkblogs. If url links to where you’re talking about a thing, then external_url links to the thing you’re talking about.
-    string title = 4; // (optional, string) is plain text. Microblog items in particular may omit titles.
-    string content_text = 5; // (optional, string) is the body of the item. It can be plain text, HTML, or a snippet of Markdown. (It should not be the entire Markdown document; just a snippet.) This is complete enough that it can be displayed alone in a reader.
-    string content_html = 6; // (optional, string) is the body of the item. It can be plain text, HTML, or a snippet of Markdown. (It should not be the entire Markdown document; just a snippet.) This is complete enough that it can be displayed alone in a reader.
-    string summary = 7; // (optional, string) is a plain text sentence or two describing the item. This might be presented in a timeline, for instance, where a detail view would display all of content_html or content_text.
-    string image = 8; // (optional, string) is the URL of the main image for the item. This image may also appear in the content_html — if so, it’s a hint to the feed reader that this is the main, featured image. Even if it’s not, it will appear in the detail view. Images should be square, with a 4:3 aspect ratio. (We will be flexible on this in the future.)
-    string banner_image = 9; // (optional, string) is the URL of an image to use as a banner. Some blogging systems (such as Medium) display a different banner image in the list view from the detail view. In those systems, this image should be used in the list view, and image in the detail view.
-    google.protobuf.Timestamp date_published = 10; // (optional, string) specifies the date in RFC 3339 format. (Example: 2010-02-07T14:04:00-05:00.)
-    google.protobuf.Timestamp date_modified = 11; // (optional, string) specifies the modification date in RFC 3339 format.
-    repeated Author authors = 12; // (optional, array of objects) has the same structure as the top-level authors. If not specified in an item, then the top-level authors, if present, are the authors of the item.
-    repeated string tags = 13; // (optional, array of strings) can have any plain text values you want. Tags tend to be just one word, but they may be anything. Note: they are not the equivalent of Twitter hashtags. Some blogging systems and other feed formats call these categories.
-    string language = 14; // (optional, string) is the language for this item, using the same format as the top-level language field. The value can be different than the primary language for the feed when a specific item is written in a different language than other items in the feed.
-    repeated Attachement attachments = 15; // (optional, array of objects) specifies the attachments associated with the item. Attachments are files that are associated with an item. The value of the attachments field is an array of objects, each of which has a url field, and other fields as specified in the attachment object definition.
+  // (required, string) is unique for that item for that feed over time. If an
+  // item is ever updated, the id should be unchanged. New items should never
+  // use a previously-used id. If an id is presented as a number or other type,
+  // a JSON Feed reader must coerce it to a string. Ideally, the id is the full
+  // URL of the resource described by the item, since URLs make great unique
+  // identifiers.
+  string id = 1;
+  // (optional, string) is the URL of the resource described by the item. It’s
+  // the permalink. This may be the same as the id — but should be present
+  // regardless.
+  string url = 2;
+  // (optional, string) is the URL of a page elsewhere. This is especially
+  // useful for linkblogs. If url links to where you’re talking about a thing,
+  // then external_url links to the thing you’re talking about.
+  string external_url = 3;
+  // (optional, string) is plain text. Microblog items in particular may omit
+  // titles.
+  string title = 4;
+  // (optional, string) is the body of the item. It can be plain text, HTML, or
+  // a snippet of Markdown. (It should not be the entire Markdown document; just
+  // a snippet.) This is complete enough that it can be displayed alone in a
+  // reader.
+  string content_text = 5;
+  // (optional, string) is the body of the item. It can be plain text, HTML, or
+  // a snippet of Markdown. (It should not be the entire Markdown document; just
+  // a snippet.) This is complete enough that it can be displayed alone in a
+  // reader.
+  string content_html = 6;
+  // (optional, string) is a plain text sentence or two describing the item.
+  // This might be presented in a timeline, for instance, where a detail view
+  // would display all of content_html or content_text.
+  string summary = 7;
+  // (optional, string) is the URL of the main image for the item. This image
+  // may also appear in the content_html — if so, it’s a hint to the feed reader
+  // that this is the main, featured image. Even if it’s not, it will appear in
+  // the detail view. Images should be square, with a 4:3 aspect ratio. (We will
+  // be flexible on this in the future.)
+  string image = 8;
+  // (optional, string) is the URL of an image to use as a banner. Some blogging
+  // systems (such as Medium) display a different banner image in the list view
+  // from the detail view. In those systems, this image should be used in the
+  // list view, and image in the detail view.
+  string banner_image = 9;
+  // (optional, string) specifies the date in RFC 3339 format.
+  google.protobuf.Timestamp date_published = 10;
+  // (optional, string) specifies the modification date in RFC 3339 format.
+  google.protobuf.Timestamp date_modified = 11;
+  // (optional, array of objects) has the same structure as the top-level
+  // authors. If not specified in an item, then the top-level authors, if
+  // present, are the authors of the item.
+  repeated Author authors = 12;
+  // (optional, array of strings) can have any plain text values you want. Tags
+  // tend to be just one word, but they may be anything. Note: they are not the
+  // equivalent of Twitter hashtags. Some blogging systems and other feed
+  // formats call these categories.
+  repeated string tags = 13;
+  // (optional, string) is the language for this item, using the same format as
+  // the top-level language field. The value can be different than the primary
+  // language for the feed when a specific item is written in a different
+  // language than other items in the feed.
+  string language = 14;
+  // (optional, array of objects) specifies the attachments associated with the
+  // item. Attachments are files that are associated with an item. The value of
+  // the attachments field is an array of objects, each of which has a url
+  // field, and other fields as specified in the attachment object definition.
+  repeated Attachement attachments = 15;
 }
 
+// Attachement is an object representing a file associated with an item.
 message Attachement {
-    string url = 1; // (required, string) specifies the location of the attachment.
-    string mime_type = 2; // (required, string) specifies the type of the attachment, such as “audio/mpeg.”
-    string title = 3; // (optional, string) specifies the title of the attachment.
-    int32 size_in_bytes = 4; // (optional, number) specifies how large the file is.
-    int32 duration_in_seconds = 5; // (optional, number) specifies how long it takes to listen to or watch, when played at normal speed.
+  // (required, string) specifies the location of the attachment.
+  string url = 1;
+  // (required, string) specifies the type of the attachment, such as
+  // “audio/mpeg.”
+  string mime_type = 2;
+  // (optional, string) specifies the title of the attachment.
+  string title = 3;
+  // (optional, number) specifies how large the file is.
+  int32 size_in_bytes = 4;
+  // (optional, number) specifies how long it takes to listen to or watch, when
+  // played at normal speed.
+  int32 duration_in_seconds = 5;
 }
\ No newline at end of file
diff --git a/pb/external/protofeed/protofeed.pb.go b/pb/external/protofeed/protofeed.pb.go
index 88e31e6..bd0696f 100644
--- a/pb/external/protofeed/protofeed.pb.go
+++ b/pb/external/protofeed/protofeed.pb.go
@@ -21,24 +21,60 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// Feed is the root of a Proto Feed document. A feed must at least contain a
+// title and items.
 type Feed struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	Version     string    `protobuf:"bytes,1,opt,name=version,proto3" json:"version,omitempty"`                              // (required, string) is the URL of the version of the format the feed uses. This should appear at the very top, though we recognize that not all JSON generators allow for ordering.
-	Title       string    `protobuf:"bytes,2,opt,name=title,proto3" json:"title,omitempty"`                                  // (required, string) is the name of the feed, which will often correspond to the name of the website (blog, for instance), though not necessarily.
-	HomePageUrl string    `protobuf:"bytes,3,opt,name=home_page_url,json=homePageUrl,proto3" json:"home_page_url,omitempty"` // (optional but strongly recommended, string) is the URL of the resource that the feed describes. This resource may or may not actually be a “home” page, but it should be an HTML page. If a feed is published on the public web, this should be considered as required. But it may not make sense in the case of a file created on a desktop computer, when that file is not shared or is shared only privately.
-	FeedUrl     string    `protobuf:"bytes,4,opt,name=feed_url,json=feedUrl,proto3" json:"feed_url,omitempty"`               // (optional but strongly recommended, string) is the URL of the feed, and serves as the unique identifier for the feed. As with home_page_url, this should be considered required for feeds on the public web.
-	Description string    `protobuf:"bytes,5,opt,name=description,proto3" json:"description,omitempty"`                      // (optional, string) provides more detail, beyond the title, on what the feed is about. A feed reader may display this text.
-	UserComment string    `protobuf:"bytes,6,opt,name=user_comment,json=userComment,proto3" json:"user_comment,omitempty"`   // (optional, string) is a description of the purpose of the feed. This is for the use of people looking at the raw JSON, and should be ignored by feed readers.
-	NextUrl     string    `protobuf:"bytes,7,opt,name=next_url,json=nextUrl,proto3" json:"next_url,omitempty"`               // (optional, string) is the URL of a feed that provides the next n items, where n is determined by the publisher. This allows for pagination, but with the expectation that reader software is not required to use it and probably won’t use it very often. next_url must not be the same as feed_url, and it must not be the same as a previous next_url.
-	Icon        string    `protobuf:"bytes,8,opt,name=icon,proto3" json:"icon,omitempty"`                                    // (optional, string) is the URL of an image for the feed suitable to be used in a source list. It should be square and relatively large — such as 512 x 512 — so that it can be scaled down and so that it can look good on retina displays. It should use transparency where appropriate, since it may be rendered on a non-white background.
-	Favicon     string    `protobuf:"bytes,9,opt,name=favicon,proto3" json:"favicon,omitempty"`                              // (optional, string) is the URL of an image for the feed suitable to be used in a source list. It should be square and relatively small, but not smaller than 64 x 64.
-	Authors     []*Author `protobuf:"bytes,10,rep,name=authors,proto3" json:"authors,omitempty"`                             // (optional, array of objects) specifies the feed authors.
-	Language    string    `protobuf:"bytes,11,opt,name=language,proto3" json:"language,omitempty"`                           // (optional, string) is the primary language for the feed.
-	Expired     bool      `protobuf:"varint,12,opt,name=expired,proto3" json:"expired,omitempty"`                            // (optional, boolean) says whether or not the feed is finished — that is, whether or not it will ever update again. A feed for a temporary event, such as an instance of the Olympics, could expire. If the value is true, then it’s expired. Any other value, or the absence of expired, means the feed may continue to update.
-	Items       []*Item   `protobuf:"bytes,13,rep,name=items,proto3" json:"items,omitempty"`                                 // (required, array of objects) contains the items in the feed. This is the most important element of the feed after the version field. Each item is a story, blog post, article, photograph, video, or other thing. For example, if a feed contains a long article, a podcast episode, and a photo, those three items would be included in items.
+	// (required, string) is the name of the feed, which will often correspond to
+	// the name of the website (blog, for instance), though not necessarily.
+	Title string `protobuf:"bytes,2,opt,name=title,proto3" json:"title,omitempty"`
+	// (optional but strongly recommended, string) is the URL of the resource that
+	// the feed describes. This resource may or may not actually be a “home” page,
+	// but it should be an HTML page. If a feed is published on the public web,
+	// this should be considered as required. But it may not make sense in the
+	// case of a file created on a desktop computer, when that file is not shared
+	// or is shared only privately.
+	HomePageUrl string `protobuf:"bytes,3,opt,name=home_page_url,json=homePageUrl,proto3" json:"home_page_url,omitempty"`
+	// (optional but strongly recommended, string) is the URL of the feed, and
+	// serves as the unique identifier for the feed. As with home_page_url, this
+	// should be considered required for feeds on the public web.
+	FeedUrl string `protobuf:"bytes,4,opt,name=feed_url,json=feedUrl,proto3" json:"feed_url,omitempty"`
+	// (optional, string) provides more detail, beyond the title, on what the feed
+	// is about. A feed reader may display this text.
+	Description string `protobuf:"bytes,5,opt,name=description,proto3" json:"description,omitempty"`
+	// (optional, string) is a description of the purpose of the feed. This is for
+	// the use of people looking at the raw Protobuf, and should be ignored by
+	// feed readers.
+	UserComment string `protobuf:"bytes,6,opt,name=user_comment,json=userComment,proto3" json:"user_comment,omitempty"`
+	// (optional, string) is the URL of an image for the feed suitable to be used
+	// in a source list. It should be square and relatively large — such as 512 x
+	// 512 — so that it can be scaled down and so that it can look good on retina
+	// displays. It should use transparency where appropriate, since it may be
+	// rendered on a non-white background.
+	Icon string `protobuf:"bytes,7,opt,name=icon,proto3" json:"icon,omitempty"`
+	// (optional, string) is the URL of an image for the feed suitable to be used
+	// in a source list. It should be square and relatively small, but not smaller
+	// than 64 x 64.
+	Favicon string `protobuf:"bytes,8,opt,name=favicon,proto3" json:"favicon,omitempty"`
+	// (optional, array of objects) specifies the feed authors.
+	Authors []*Author `protobuf:"bytes,9,rep,name=authors,proto3" json:"authors,omitempty"`
+	// (optional, string) is the primary language for the feed.
+	Language string `protobuf:"bytes,10,opt,name=language,proto3" json:"language,omitempty"`
+	// (optional, boolean) says whether or not the feed is finished — that is,
+	// whether or not it will ever update again. A feed for a temporary event,
+	// such as an instance of the Olympics, could expire. If the value is true,
+	// then it’s expired. Any other value, or the absence of expired, means the
+	// feed may continue to update.
+	Expired bool `protobuf:"varint,11,opt,name=expired,proto3" json:"expired,omitempty"`
+	// (required, array of objects) contains the items in the feed. This is the
+	// most important element of the feed after the version field. Each item is a
+	// story, blog post, article, photograph, video, or other thing. For example,
+	// if a feed contains a long article, a podcast episode, and a photo, those
+	// three items would be included in items.
+	Items []*Item `protobuf:"bytes,12,rep,name=items,proto3" json:"items,omitempty"`
 }
 
 func (x *Feed) Reset() {
@@ -73,13 +109,6 @@ func (*Feed) Descriptor() ([]byte, []int) {
 	return file_protofeed_proto_rawDescGZIP(), []int{0}
 }
 
-func (x *Feed) GetVersion() string {
-	if x != nil {
-		return x.Version
-	}
-	return ""
-}
-
 func (x *Feed) GetTitle() string {
 	if x != nil {
 		return x.Title
@@ -115,13 +144,6 @@ func (x *Feed) GetUserComment() string {
 	return ""
 }
 
-func (x *Feed) GetNextUrl() string {
-	if x != nil {
-		return x.NextUrl
-	}
-	return ""
-}
-
 func (x *Feed) GetIcon() string {
 	if x != nil {
 		return x.Icon
@@ -164,14 +186,24 @@ func (x *Feed) GetItems() []*Item {
 	return nil
 }
 
+// Author is an object representing the author of the feed or item.
 type Author struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	Name   string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`     // (optional, string) is the author’s name.
-	Url    string `protobuf:"bytes,2,opt,name=url,proto3" json:"url,omitempty"`       // (optional, string) is the URL of a site owned by the author. It could be a blog, micro-blog, Twitter account, and so on. Ideally the linked-to page provides a way to contact the author, but that’s not required. The URL could be a mailto: link, though we suspect that will be rare.
-	Avatar string `protobuf:"bytes,3,opt,name=avatar,proto3" json:"avatar,omitempty"` // (optional, string) is the URL for an image for the author. As with icon, it should be square and relatively large — such as 512 x 512 pixels — and should use transparency where appropriate, since it may be rendered on a non-white background.
+	// (optional, string) is the author’s name.
+	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// (optional, string) is the URL of a site owned by the author. It could be a
+	// blog, micro-blog, Twitter account, and so on. Ideally the linked-to page
+	// provides a way to contact the author, but that’s not required. The URL
+	// could be a mailto: link, though we suspect that will be rare.
+	Url string `protobuf:"bytes,2,opt,name=url,proto3" json:"url,omitempty"`
+	// (optional, string) is the URL for an image for the author. As with icon, it
+	// should be square and relatively large — such as 512 x 512 pixels — and
+	// should use transparency where appropriate, since it may be rendered on a
+	// non-white background.
+	Avatar string `protobuf:"bytes,3,opt,name=avatar,proto3" json:"avatar,omitempty"`
 }
 
 func (x *Author) Reset() {
@@ -227,26 +259,79 @@ func (x *Author) GetAvatar() string {
 	return ""
 }
 
+// Item is an object representing a single story, blog post, article,
+// photograph, video, or other thing within a feed.
 type Item struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	Id            string                 `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`                                             // (required, string) is unique for that item for that feed over time. If an item is ever updated, the id should be unchanged. New items should never use a previously-used id. If an id is presented as a number or other type, a JSON Feed reader must coerce it to a string. Ideally, the id is the full URL of the resource described by the item, since URLs make great unique identifiers.
-	Url           string                 `protobuf:"bytes,2,opt,name=url,proto3" json:"url,omitempty"`                                           // (optional, string) is the URL of the resource described by the item. It’s the permalink. This may be the same as the id — but should be present regardless.
-	ExternalUrl   string                 `protobuf:"bytes,3,opt,name=external_url,json=externalUrl,proto3" json:"external_url,omitempty"`        // (optional, string) is the URL of a page elsewhere. This is especially useful for linkblogs. If url links to where you’re talking about a thing, then external_url links to the thing you’re talking about.
-	Title         string                 `protobuf:"bytes,4,opt,name=title,proto3" json:"title,omitempty"`                                       // (optional, string) is plain text. Microblog items in particular may omit titles.
-	ContentText   string                 `protobuf:"bytes,5,opt,name=content_text,json=contentText,proto3" json:"content_text,omitempty"`        // (optional, string) is the body of the item. It can be plain text, HTML, or a snippet of Markdown. (It should not be the entire Markdown document; just a snippet.) This is complete enough that it can be displayed alone in a reader.
-	ContentHtml   string                 `protobuf:"bytes,6,opt,name=content_html,json=contentHtml,proto3" json:"content_html,omitempty"`        // (optional, string) is the body of the item. It can be plain text, HTML, or a snippet of Markdown. (It should not be the entire Markdown document; just a snippet.) This is complete enough that it can be displayed alone in a reader.
-	Summary       string                 `protobuf:"bytes,7,opt,name=summary,proto3" json:"summary,omitempty"`                                   // (optional, string) is a plain text sentence or two describing the item. This might be presented in a timeline, for instance, where a detail view would display all of content_html or content_text.
-	Image         string                 `protobuf:"bytes,8,opt,name=image,proto3" json:"image,omitempty"`                                       // (optional, string) is the URL of the main image for the item. This image may also appear in the content_html — if so, it’s a hint to the feed reader that this is the main, featured image. Even if it’s not, it will appear in the detail view. Images should be square, with a 4:3 aspect ratio. (We will be flexible on this in the future.)
-	BannerImage   string                 `protobuf:"bytes,9,opt,name=banner_image,json=bannerImage,proto3" json:"banner_image,omitempty"`        // (optional, string) is the URL of an image to use as a banner. Some blogging systems (such as Medium) display a different banner image in the list view from the detail view. In those systems, this image should be used in the list view, and image in the detail view.
-	DatePublished *timestamppb.Timestamp `protobuf:"bytes,10,opt,name=date_published,json=datePublished,proto3" json:"date_published,omitempty"` // (optional, string) specifies the date in RFC 3339 format. (Example: 2010-02-07T14:04:00-05:00.)
-	DateModified  *timestamppb.Timestamp `protobuf:"bytes,11,opt,name=date_modified,json=dateModified,proto3" json:"date_modified,omitempty"`    // (optional, string) specifies the modification date in RFC 3339 format.
-	Authors       []*Author              `protobuf:"bytes,12,rep,name=authors,proto3" json:"authors,omitempty"`                                  // (optional, array of objects) has the same structure as the top-level authors. If not specified in an item, then the top-level authors, if present, are the authors of the item.
-	Tags          []string               `protobuf:"bytes,13,rep,name=tags,proto3" json:"tags,omitempty"`                                        // (optional, array of strings) can have any plain text values you want. Tags tend to be just one word, but they may be anything. Note: they are not the equivalent of Twitter hashtags. Some blogging systems and other feed formats call these categories.
-	Language      string                 `protobuf:"bytes,14,opt,name=language,proto3" json:"language,omitempty"`                                // (optional, string) is the language for this item, using the same format as the top-level language field. The value can be different than the primary language for the feed when a specific item is written in a different language than other items in the feed.
-	Attachments   []*Attachement         `protobuf:"bytes,15,rep,name=attachments,proto3" json:"attachments,omitempty"`                          // (optional, array of objects) specifies the attachments associated with the item. Attachments are files that are associated with an item. The value of the attachments field is an array of objects, each of which has a url field, and other fields as specified in the attachment object definition.
+	// (required, string) is unique for that item for that feed over time. If an
+	// item is ever updated, the id should be unchanged. New items should never
+	// use a previously-used id. If an id is presented as a number or other type,
+	// a JSON Feed reader must coerce it to a string. Ideally, the id is the full
+	// URL of the resource described by the item, since URLs make great unique
+	// identifiers.
+	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	// (optional, string) is the URL of the resource described by the item. It’s
+	// the permalink. This may be the same as the id — but should be present
+	// regardless.
+	Url string `protobuf:"bytes,2,opt,name=url,proto3" json:"url,omitempty"`
+	// (optional, string) is the URL of a page elsewhere. This is especially
+	// useful for linkblogs. If url links to where you’re talking about a thing,
+	// then external_url links to the thing you’re talking about.
+	ExternalUrl string `protobuf:"bytes,3,opt,name=external_url,json=externalUrl,proto3" json:"external_url,omitempty"`
+	// (optional, string) is plain text. Microblog items in particular may omit
+	// titles.
+	Title string `protobuf:"bytes,4,opt,name=title,proto3" json:"title,omitempty"`
+	// (optional, string) is the body of the item. It can be plain text, HTML, or
+	// a snippet of Markdown. (It should not be the entire Markdown document; just
+	// a snippet.) This is complete enough that it can be displayed alone in a
+	// reader.
+	ContentText string `protobuf:"bytes,5,opt,name=content_text,json=contentText,proto3" json:"content_text,omitempty"`
+	// (optional, string) is the body of the item. It can be plain text, HTML, or
+	// a snippet of Markdown. (It should not be the entire Markdown document; just
+	// a snippet.) This is complete enough that it can be displayed alone in a
+	// reader.
+	ContentHtml string `protobuf:"bytes,6,opt,name=content_html,json=contentHtml,proto3" json:"content_html,omitempty"`
+	// (optional, string) is a plain text sentence or two describing the item.
+	// This might be presented in a timeline, for instance, where a detail view
+	// would display all of content_html or content_text.
+	Summary string `protobuf:"bytes,7,opt,name=summary,proto3" json:"summary,omitempty"`
+	// (optional, string) is the URL of the main image for the item. This image
+	// may also appear in the content_html — if so, it’s a hint to the feed reader
+	// that this is the main, featured image. Even if it’s not, it will appear in
+	// the detail view. Images should be square, with a 4:3 aspect ratio. (We will
+	// be flexible on this in the future.)
+	Image string `protobuf:"bytes,8,opt,name=image,proto3" json:"image,omitempty"`
+	// (optional, string) is the URL of an image to use as a banner. Some blogging
+	// systems (such as Medium) display a different banner image in the list view
+	// from the detail view. In those systems, this image should be used in the
+	// list view, and image in the detail view.
+	BannerImage string `protobuf:"bytes,9,opt,name=banner_image,json=bannerImage,proto3" json:"banner_image,omitempty"`
+	// (optional, string) specifies the date in RFC 3339 format.
+	DatePublished *timestamppb.Timestamp `protobuf:"bytes,10,opt,name=date_published,json=datePublished,proto3" json:"date_published,omitempty"`
+	// (optional, string) specifies the modification date in RFC 3339 format.
+	DateModified *timestamppb.Timestamp `protobuf:"bytes,11,opt,name=date_modified,json=dateModified,proto3" json:"date_modified,omitempty"`
+	// (optional, array of objects) has the same structure as the top-level
+	// authors. If not specified in an item, then the top-level authors, if
+	// present, are the authors of the item.
+	Authors []*Author `protobuf:"bytes,12,rep,name=authors,proto3" json:"authors,omitempty"`
+	// (optional, array of strings) can have any plain text values you want. Tags
+	// tend to be just one word, but they may be anything. Note: they are not the
+	// equivalent of Twitter hashtags. Some blogging systems and other feed
+	// formats call these categories.
+	Tags []string `protobuf:"bytes,13,rep,name=tags,proto3" json:"tags,omitempty"`
+	// (optional, string) is the language for this item, using the same format as
+	// the top-level language field. The value can be different than the primary
+	// language for the feed when a specific item is written in a different
+	// language than other items in the feed.
+	Language string `protobuf:"bytes,14,opt,name=language,proto3" json:"language,omitempty"`
+	// (optional, array of objects) specifies the attachments associated with the
+	// item. Attachments are files that are associated with an item. The value of
+	// the attachments field is an array of objects, each of which has a url
+	// field, and other fields as specified in the attachment object definition.
+	Attachments []*Attachement `protobuf:"bytes,15,rep,name=attachments,proto3" json:"attachments,omitempty"`
 }
 
 func (x *Item) Reset() {
@@ -386,16 +471,24 @@ func (x *Item) GetAttachments() []*Attachement {
 	return nil
 }
 
+// Attachement is an object representing a file associated with an item.
 type Attachement struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	Url               string `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"`                                                         // (required, string) specifies the location of the attachment.
-	MimeType          string `protobuf:"bytes,2,opt,name=mime_type,json=mimeType,proto3" json:"mime_type,omitempty"`                               // (required, string) specifies the type of the attachment, such as “audio/mpeg.”
-	Title             string `protobuf:"bytes,3,opt,name=title,proto3" json:"title,omitempty"`                                                     // (optional, string) specifies the title of the attachment.
-	SizeInBytes       int32  `protobuf:"varint,4,opt,name=size_in_bytes,json=sizeInBytes,proto3" json:"size_in_bytes,omitempty"`                   // (optional, number) specifies how large the file is.
-	DurationInSeconds int32  `protobuf:"varint,5,opt,name=duration_in_seconds,json=durationInSeconds,proto3" json:"duration_in_seconds,omitempty"` // (optional, number) specifies how long it takes to listen to or watch, when played at normal speed.
+	// (required, string) specifies the location of the attachment.
+	Url string `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"`
+	// (required, string) specifies the type of the attachment, such as
+	// “audio/mpeg.”
+	MimeType string `protobuf:"bytes,2,opt,name=mime_type,json=mimeType,proto3" json:"mime_type,omitempty"`
+	// (optional, string) specifies the title of the attachment.
+	Title string `protobuf:"bytes,3,opt,name=title,proto3" json:"title,omitempty"`
+	// (optional, number) specifies how large the file is.
+	SizeInBytes int32 `protobuf:"varint,4,opt,name=size_in_bytes,json=sizeInBytes,proto3" json:"size_in_bytes,omitempty"`
+	// (optional, number) specifies how long it takes to listen to or watch, when
+	// played at normal speed.
+	DurationInSeconds int32 `protobuf:"varint,5,opt,name=duration_in_seconds,json=durationInSeconds,proto3" json:"duration_in_seconds,omitempty"`
 }
 
 func (x *Attachement) Reset() {
@@ -472,86 +565,83 @@ var file_protofeed_proto_rawDesc = []byte{
 	0x6f, 0x12, 0x14, 0x78, 0x65, 0x69, 0x61, 0x73, 0x6f, 0x2e, 0x6e, 0x65, 0x74, 0x2e, 0x70, 0x72,
 	0x6f, 0x74, 0x6f, 0x66, 0x65, 0x65, 0x64, 0x1a, 0x1f, 0x67, 0x6f, 0x6f, 0x67, 0x6c, 0x65, 0x2f,
 	0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62, 0x75, 0x66, 0x2f, 0x74, 0x69, 0x6d, 0x65, 0x73, 0x74, 0x61,
-	0x6d, 0x70, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x22, 0xa3, 0x03, 0x0a, 0x04, 0x46, 0x65, 0x65,
-	0x64, 0x12, 0x18, 0x0a, 0x07, 0x76, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0x18, 0x01, 0x20, 0x01,
-	0x28, 0x09, 0x52, 0x07, 0x76, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, 0x12, 0x14, 0x0a, 0x05, 0x74,
-	0x69, 0x74, 0x6c, 0x65, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x05, 0x74, 0x69, 0x74, 0x6c,
-	0x65, 0x12, 0x22, 0x0a, 0x0d, 0x68, 0x6f, 0x6d, 0x65, 0x5f, 0x70, 0x61, 0x67, 0x65, 0x5f, 0x75,
-	0x72, 0x6c, 0x18, 0x03, 0x20, 0x01, 0x28, 0x09, 0x52, 0x0b, 0x68, 0x6f, 0x6d, 0x65, 0x50, 0x61,
-	0x67, 0x65, 0x55, 0x72, 0x6c, 0x12, 0x19, 0x0a, 0x08, 0x66, 0x65, 0x65, 0x64, 0x5f, 0x75, 0x72,
-	0x6c, 0x18, 0x04, 0x20, 0x01, 0x28, 0x09, 0x52, 0x07, 0x66, 0x65, 0x65, 0x64, 0x55, 0x72, 0x6c,
-	0x12, 0x20, 0x0a, 0x0b, 0x64, 0x65, 0x73, 0x63, 0x72, 0x69, 0x70, 0x74, 0x69, 0x6f, 0x6e, 0x18,
-	0x05, 0x20, 0x01, 0x28, 0x09, 0x52, 0x0b, 0x64, 0x65, 0x73, 0x63, 0x72, 0x69, 0x70, 0x74, 0x69,
-	0x6f, 0x6e, 0x12, 0x21, 0x0a, 0x0c, 0x75, 0x73, 0x65, 0x72, 0x5f, 0x63, 0x6f, 0x6d, 0x6d, 0x65,
-	0x6e, 0x74, 0x18, 0x06, 0x20, 0x01, 0x28, 0x09, 0x52, 0x0b, 0x75, 0x73, 0x65, 0x72, 0x43, 0x6f,
-	0x6d, 0x6d, 0x65, 0x6e, 0x74, 0x12, 0x19, 0x0a, 0x08, 0x6e, 0x65, 0x78, 0x74, 0x5f, 0x75, 0x72,
-	0x6c, 0x18, 0x07, 0x20, 0x01, 0x28, 0x09, 0x52, 0x07, 0x6e, 0x65, 0x78, 0x74, 0x55, 0x72, 0x6c,
-	0x12, 0x12, 0x0a, 0x04, 0x69, 0x63, 0x6f, 0x6e, 0x18, 0x08, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04,
-	0x69, 0x63, 0x6f, 0x6e, 0x12, 0x18, 0x0a, 0x07, 0x66, 0x61, 0x76, 0x69, 0x63, 0x6f, 0x6e, 0x18,
-	0x09, 0x20, 0x01, 0x28, 0x09, 0x52, 0x07, 0x66, 0x61, 0x76, 0x69, 0x63, 0x6f, 0x6e, 0x12, 0x36,
-	0x0a, 0x07, 0x61, 0x75, 0x74, 0x68, 0x6f, 0x72, 0x73, 0x18, 0x0a, 0x20, 0x03, 0x28, 0x0b, 0x32,
-	0x1c, 0x2e, 0x78, 0x65, 0x69, 0x61, 0x73, 0x6f, 0x2e, 0x6e, 0x65, 0x74, 0x2e, 0x70, 0x72, 0x6f,
-	0x74, 0x6f, 0x66, 0x65, 0x65, 0x64, 0x2e, 0x41, 0x75, 0x74, 0x68, 0x6f, 0x72, 0x52, 0x07, 0x61,
-	0x75, 0x74, 0x68, 0x6f, 0x72, 0x73, 0x12, 0x1a, 0x0a, 0x08, 0x6c, 0x61, 0x6e, 0x67, 0x75, 0x61,
-	0x67, 0x65, 0x18, 0x0b, 0x20, 0x01, 0x28, 0x09, 0x52, 0x08, 0x6c, 0x61, 0x6e, 0x67, 0x75, 0x61,
-	0x67, 0x65, 0x12, 0x18, 0x0a, 0x07, 0x65, 0x78, 0x70, 0x69, 0x72, 0x65, 0x64, 0x18, 0x0c, 0x20,
-	0x01, 0x28, 0x08, 0x52, 0x07, 0x65, 0x78, 0x70, 0x69, 0x72, 0x65, 0x64, 0x12, 0x30, 0x0a, 0x05,
-	0x69, 0x74, 0x65, 0x6d, 0x73, 0x18, 0x0d, 0x20, 0x03, 0x28, 0x0b, 0x32, 0x1a, 0x2e, 0x78, 0x65,
-	0x69, 0x61, 0x73, 0x6f, 0x2e, 0x6e, 0x65, 0x74, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x66, 0x65,
-	0x65, 0x64, 0x2e, 0x49, 0x74, 0x65, 0x6d, 0x52, 0x05, 0x69, 0x74, 0x65, 0x6d, 0x73, 0x22, 0x46,
-	0x0a, 0x06, 0x41, 0x75, 0x74, 0x68, 0x6f, 0x72, 0x12, 0x12, 0x0a, 0x04, 0x6e, 0x61, 0x6d, 0x65,
-	0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04, 0x6e, 0x61, 0x6d, 0x65, 0x12, 0x10, 0x0a, 0x03,
-	0x75, 0x72, 0x6c, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x03, 0x75, 0x72, 0x6c, 0x12, 0x16,
-	0x0a, 0x06, 0x61, 0x76, 0x61, 0x74, 0x61, 0x72, 0x18, 0x03, 0x20, 0x01, 0x28, 0x09, 0x52, 0x06,
-	0x61, 0x76, 0x61, 0x74, 0x61, 0x72, 0x22, 0xab, 0x04, 0x0a, 0x04, 0x49, 0x74, 0x65, 0x6d, 0x12,
-	0x0e, 0x0a, 0x02, 0x69, 0x64, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x02, 0x69, 0x64, 0x12,
-	0x10, 0x0a, 0x03, 0x75, 0x72, 0x6c, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x03, 0x75, 0x72,
-	0x6c, 0x12, 0x21, 0x0a, 0x0c, 0x65, 0x78, 0x74, 0x65, 0x72, 0x6e, 0x61, 0x6c, 0x5f, 0x75, 0x72,
-	0x6c, 0x18, 0x03, 0x20, 0x01, 0x28, 0x09, 0x52, 0x0b, 0x65, 0x78, 0x74, 0x65, 0x72, 0x6e, 0x61,
-	0x6c, 0x55, 0x72, 0x6c, 0x12, 0x14, 0x0a, 0x05, 0x74, 0x69, 0x74, 0x6c, 0x65, 0x18, 0x04, 0x20,
-	0x01, 0x28, 0x09, 0x52, 0x05, 0x74, 0x69, 0x74, 0x6c, 0x65, 0x12, 0x21, 0x0a, 0x0c, 0x63, 0x6f,
-	0x6e, 0x74, 0x65, 0x6e, 0x74, 0x5f, 0x74, 0x65, 0x78, 0x74, 0x18, 0x05, 0x20, 0x01, 0x28, 0x09,
-	0x52, 0x0b, 0x63, 0x6f, 0x6e, 0x74, 0x65, 0x6e, 0x74, 0x54, 0x65, 0x78, 0x74, 0x12, 0x21, 0x0a,
-	0x0c, 0x63, 0x6f, 0x6e, 0x74, 0x65, 0x6e, 0x74, 0x5f, 0x68, 0x74, 0x6d, 0x6c, 0x18, 0x06, 0x20,
-	0x01, 0x28, 0x09, 0x52, 0x0b, 0x63, 0x6f, 0x6e, 0x74, 0x65, 0x6e, 0x74, 0x48, 0x74, 0x6d, 0x6c,
-	0x12, 0x18, 0x0a, 0x07, 0x73, 0x75, 0x6d, 0x6d, 0x61, 0x72, 0x79, 0x18, 0x07, 0x20, 0x01, 0x28,
-	0x09, 0x52, 0x07, 0x73, 0x75, 0x6d, 0x6d, 0x61, 0x72, 0x79, 0x12, 0x14, 0x0a, 0x0