Updated MandatoryProjectDataType JSDoc to match current type enforcem…

…ent (#690)
paranext · Dec 21, 2023 · c15dc2e · c15dc2e
2 parents 35bd959 + 0560c0c
commit c15dc2e
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 2 deletions.
diff --git a/lib/papi-dts/papi.d.ts b/lib/papi-dts/papi.d.ts
@@ -2184,7 +2184,21 @@ declare module 'shared/models/project-data-provider.model' {
      */
     dataQualifier: string;
   };
-  /** All Project Data Provider data types must extend from this */
+  /**
+   * All Project Data Provider data types must have an `ExtensionData` type. We strongly recommend all
+   * Project Data Provider data types extend from this type in order to standardize the
+   * `ExtensionData` types.
+   *
+   * Benefits of following this standard:
+   *
+   * - All PSIs that support this `projectType` can use a standardized `ExtensionData` interface
+   * - If an extension uses the `ExtensionData` endpoint for any project, it will likely use this
+   *   standardized interface, so using this interface on your Project Data Provider data types
+   *   enables your PDP to support generic extension data
+   * - In the future, we may enforce that callers to `ExtensionData` endpoints include `extensionName`,
+   *   so following this interface ensures your PDP will not break if such a requirement is
+   *   implemented.
+   */
   export type MandatoryProjectDataType = {
     ExtensionData: DataProviderDataType<ExtensionDataScope, string | undefined, string>;
   };

diff --git a/src/shared/models/project-data-provider.model.ts b/src/shared/models/project-data-provider.model.ts
@@ -18,7 +18,21 @@ export type ExtensionDataScope = {
   dataQualifier: string;
 };
 
-/** All Project Data Provider data types must extend from this */
+/**
+ * All Project Data Provider data types must have an `ExtensionData` type. We strongly recommend all
+ * Project Data Provider data types extend from this type in order to standardize the
+ * `ExtensionData` types.
+ *
+ * Benefits of following this standard:
+ *
+ * - All PSIs that support this `projectType` can use a standardized `ExtensionData` interface
+ * - If an extension uses the `ExtensionData` endpoint for any project, it will likely use this
+ *   standardized interface, so using this interface on your Project Data Provider data types
+ *   enables your PDP to support generic extension data
+ * - In the future, we may enforce that callers to `ExtensionData` endpoints include `extensionName`,
+ *   so following this interface ensures your PDP will not break if such a requirement is
+ *   implemented.
+ */
 export type MandatoryProjectDataType = {
   ExtensionData: DataProviderDataType<ExtensionDataScope, string | undefined, string>;
 };