docs: clarify trends suggestion policy

Author: pastelsky

pages/trends/trendsAutocomplete.ts

@@ -24,6 +24,8 @@ export function rankSuggestionsByQuery(
       suggestion.package.name.toLowerCase().includes(normalizedQuery)
     )
     .sort((a, b) => {
+      // A direct match is more useful than a package that merely contains the
+      // typed name, regardless of its score.
       const aStartsWithQuery = a.package.name
         .toLowerCase()
         .startsWith(normalizedQuery)
@@ -43,13 +45,16 @@ export async function loadRelatedPackageSuggestions(
   query: string,
   relatedPackageNames: string[]
 ) {
+  // Related packages expand discovery, but keep the request fan-out bounded
+  // while a user is typing.
   const queries = [query, ...relatedPackageNames]
     .filter(Boolean)
     .slice(0, MAX_RELATED_PACKAGES + 1)
   const results = await Promise.allSettled(
     queries.map(packageName => API.getSuggestions(packageName))
   )
 
+  // A failed related lookup should not hide suggestions from successful ones.
   return rankSuggestionsByQuery(
     results.flatMap(result =>
       result.status === 'fulfilled' ? result.value : []