correct schema doc

ingest/schema/doc.go

@@ -1,22 +1,21 @@
-// Package schema defines the makeup of an advertisement.  An advertisement is
+// Package schema defines the makeup of an advertisement. An advertisement is
 // used to inform an indexer that there are updates to a provider's content.
-// The IsRm and Entries fields determine how the indexer handles
-// the advertisement. The following table describes this:
+// The IsRm and Entries fields determine how the indexer handles the
+// advertisement, as described by the following table:
 //
 //	IsRm    Entries    Action
 //
 // ------+-----------+------------------------------------
 // false | NoEntries | Update metadata
 // false | data      | Update metadata and index entries
 // true  | NoEntries | Delete content with context ID
-// true  | data      | Delete specific multihash indexes *
+// true  | data      | Delete content with context ID (ignore entries)
 //
-// * Deleting entries still requires a context ID, because a multihash can map
-// to multiple contextID/metadata values.
+// When removing content (IsRm true) the metadata and entries are ignored. An
+// advertisement that removes content cannot have extended provider
+// information.
 //
-// When removing content (IsRm true) the metadata is ignored.
-//
-// All advertisements update the provider's addresses.  To create an
+// All advertisements update the provider's addresses. To create an
 // advertisement that only updates a provider's address, create an
-// advertisement to remove content using a context ID that is not used.
+// advertisement that contains no metadata and no entries.
 package schema

pcache/doc.go

@@ -7,14 +7,14 @@
 // cache reads, such as those that must quickly deliver IPNI find results, or
 // that handle a high volume of provider information requests.
 //
-// ## Multiple Overlapping Data Sources
+// # Multiple Overlapping Data Sources
 //
 // The cache can be configured with multiple data sources from which provider
 // information is fetched. If the same provider information is returned from
 // multiple data sources, then the information with the most recent timestamp
 // is used.
 //
-// ## All Provider Information Cached
+// # All Provider Information Cached
 //
 // The provider cache maintains a unified view of all provider information
 // across all data sources. Caching provider information in builk allows the
@@ -23,7 +23,7 @@
 // important when there are multiple sources to fetch provider information
 // from, and when responses include infomration about multiple providers.
 //
-// ## Cache Refresh
+// # Cache Refresh
 //
 // If the cache refresh interval is non-zero (default is 2 minutes), then after
 // that time is elapsed, a timer sets a flag to indicate that refresh is
@@ -38,7 +38,7 @@
 // of the cached data is built, and is then atomically set as the cache's
 // read-only lock-free data.
 //
-// ## Negative Cache
+// # Negative Cache
 //
 // Lookups for provider information that are not currently cached will generate
 // an initial query to the cache's data sources. If the information is found
@@ -47,7 +47,7 @@
 // data sources. If the information becomes available the negative cache entry
 // is replaced at the next refresh.
 //
-// ## Cache Eviction
+// # Cache Eviction
 //
 // Cached provider information remains in the cache until the information is no
 // longer available from any of the sources for longer than the configured