From 1baa808e0fd26f121ea27b865f6dd6cffdcedf40 Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Fri, 13 Sep 2024 10:53:43 -0400
Subject: [PATCH] finish up comments on productSlugs

---
 src/lib/products.ts | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/lib/products.ts b/src/lib/products.ts
index a36d2f16be..791ebf980e 100644
--- a/src/lib/products.ts
+++ b/src/lib/products.ts
@@ -45,9 +45,13 @@ import { Product, ProductName, ProductSlug } from 'types/products'
  * - rewrite-tutorial-links.test.ts (devDotTutorialsPath)
  *
  * TYPE ASSERTION USES
- * - isProductSlug (generic assertion across content types? need to investigate)
+ * - isProductSlug - this feels like it might be used as generic assertion
+ *   across content types. It might be helpful to create more specific type
+ *   guards, eg `isProductSlugWithLogo`, `isProductSlugWithDocs`,
+ *   `isProductSlugWithLandingPage`, `isProductSlugWithTutorials`,
+ *   `isProductSlugWithIntegrations`, etc.
  *
- * LEGACY DOT-IO MIGRATION USES
+ * LEGACY DOT-IO MIGRATION USES (assumes a dot-io site existed for the product)
  * - getIsRewriteableDocsLink (and related tests)
  * - rewrite-tutorial-links tests ("Links to .io home pages are not rewritten")
  *
@@ -55,10 +59,16 @@ import { Product, ProductName, ProductSlug } from 'types/products'
  * avoided adding to this constant because of how it's intertwined with other
  * purposes. It probably makes sense for us to refactor some code so that we're
  * only ever using this constant as a way to get the product name from a given
- * product slug. For all other uses cases, it might feel duplicative, but
- * explicitly declaring new constants (not filtered from some "main" const)
- * will likely make our codebase easier to understand and work with as we
- * add new "products" such as HCP Vault Secrets, etc.
+ * product slug (where "product slug" is any valid product slug across any
+ * use case).
+ *
+ * For all other uses cases, it might feel duplicative, but one approach might
+ * be to explicitly declare new constants for each use case. Or maybe, since
+ * much of these use cases rely on data that could be encoded in our existing
+ * `src/data/<product>.json` files, we'd could gather everything related to
+ * each product in those files, and derive the maps we need from the already
+ * exported `PRODUCT_DATA_MAP`. Or maybe there's some other approach that we
+ * could use to simplify our setup... It feels a bit convoluted right now.
  */
 const productSlugsToNames: { [slug in ProductSlug]: ProductName } = {
 	hcp: 'HashiCorp Cloud Platform',