Add an option to generate a doc comment on the value. (#4904)

microsoft · Aug 26, 2024 · d4ff309 · d4ff309
1 parent ac0d63f
commit d4ff309
Show file tree

Hide file tree

Showing 17 changed files with 214 additions and 37 deletions.
diff --git a/build-tests/localization-plugin-test-02/config/heft.json b/build-tests/localization-plugin-test-02/config/heft.json
@@ -14,7 +14,12 @@
           "taskPlugin": {
             "pluginPackage": "@rushstack/heft-localization-typings-plugin",
             "options": {
-              "generatedTsFolder": "temp/loc-json-ts"
+              "generatedTsFolder": "temp/loc-json-ts",
+              "exportAsDefault": {
+                "interfaceDocumentationComment": "This interface represents a JSON object that has been loaded from a localization file.",
+                "valueDocumentationComment": "@public",
+                "inferInterfaceNameFromFilename": true
+              }
             }
           }
         },

diff --git a/build-tests/localization-plugin-test-02/src/chunks/chunkWithStrings.ts b/build-tests/localization-plugin-test-02/src/chunks/chunkWithStrings.ts
@@ -1,6 +1,6 @@
 import * as lodash from 'lodash';
 
-import * as strings from './strings2.loc.json';
+import strings from './strings2.loc.json';
 
 export class ChunkWithStringsClass {
   public doStuff(): void {

diff --git a/build-tests/localization-plugin-test-02/src/indexA.ts b/build-tests/localization-plugin-test-02/src/indexA.ts
@@ -1,8 +1,8 @@
-import { string1 } from './strings1.loc.json';
-import * as strings3 from './strings3.resjson';
-import * as strings5 from './strings5.resx';
+import strings1 from './strings1.loc.json';
+import strings3 from './strings3.resjson';
+import strings5 from './strings5.resx';
 
-console.log(string1);
+console.log(strings1.string1);
 
 console.log(strings3.string2);
 /*! Preserved comment */

diff --git a/build-tests/localization-plugin-test-02/src/indexB.ts b/build-tests/localization-plugin-test-02/src/indexB.ts
@@ -1,7 +1,7 @@
-import { string1, string2 } from './strings3.resjson';
+import strings3 from './strings3.resjson';
 const strings4: string = require('./strings4.loc.json');
 
-console.log(string1);
-console.log(string2);
+console.log(strings3.string1);
+console.log(strings3.string2);
 
 console.log(strings4);
diff --git a/...ack/heft-localization-typings-plugin/loc-typings-export-doc-comment_2024-08-26-00-26.json b/...ack/heft-localization-typings-plugin/loc-typings-export-doc-comment_2024-08-26-00-26.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-localization-typings-plugin",
+      "comment": "Add a `valueDocumentationComment` option to `exportAsDefault` that allows a documentation comment to be generated for the exported value.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-localization-typings-plugin"
+}
diff --git a/...ack/heft-localization-typings-plugin/loc-typings-export-doc-comment_2024-08-26-00-28.json b/...ack/heft-localization-typings-plugin/loc-typings-export-doc-comment_2024-08-26-00-28.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-localization-typings-plugin",
+      "comment": "Rename the `documentationComment` property in the `exportAsDefault` value to `interfaceDocumentationComment`.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-localization-typings-plugin"
+}
diff --git a/...es/@rushstack/localization-utilities/loc-typings-export-doc-comment_2024-08-26-00-26.json b/...es/@rushstack/localization-utilities/loc-typings-export-doc-comment_2024-08-26-00-26.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/localization-utilities",
+      "comment": "Add a `valueDocumentationComment` option to `exportAsDefault` that allows a documentation comment to be generated for the exported value.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/localization-utilities"
+}
diff --git a/...es/@rushstack/localization-utilities/loc-typings-export-doc-comment_2024-08-26-00-28.json b/...es/@rushstack/localization-utilities/loc-typings-export-doc-comment_2024-08-26-00-28.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/localization-utilities",
+      "comment": "Rename the `documentationComment` property in the `exportAsDefault` value to `interfaceDocumentationComment`.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/localization-utilities"
+}
diff --git a/...changes/@rushstack/typings-generator/loc-typings-export-doc-comment_2024-08-26-00-26.json b/...changes/@rushstack/typings-generator/loc-typings-export-doc-comment_2024-08-26-00-26.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/typings-generator",
+      "comment": "Add a `valueDocumentationComment` option to `exportAsDefault` that allows a documentation comment to be generated for the exported value.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/typings-generator"
+}
diff --git a/...changes/@rushstack/typings-generator/loc-typings-export-doc-comment_2024-08-26-00-28.json b/...changes/@rushstack/typings-generator/loc-typings-export-doc-comment_2024-08-26-00-28.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/typings-generator",
+      "comment": "Rename the `documentationComment` property in the `exportAsDefault` value to `interfaceDocumentationComment`.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/typings-generator"
+}
diff --git a/common/reviews/api/typings-generator.api.md b/common/reviews/api/typings-generator.api.md
@@ -8,8 +8,11 @@ import { ITerminal } from '@rushstack/terminal';
 
 // @public (undocumented)
 export interface IExportAsDefaultOptions {
+    // @deprecated (undocumented)
     documentationComment?: string;
+    interfaceDocumentationComment?: string;
     interfaceName?: string;
+    valueDocumentationComment?: string;
 }
 
 // @public (undocumented)

diff --git a/heft-plugins/heft-localization-typings-plugin/heft-plugin.json b/heft-plugins/heft-localization-typings-plugin/heft-plugin.json
@@ -1,5 +1,5 @@
 {
-  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft-plugin.schema.json",
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft-plugin.schema.json",
 
   "taskPlugins": [
     {

diff --git a/heft-plugins/heft-localization-typings-plugin/src/schemas/options.schema.json b/heft-plugins/heft-localization-typings-plugin/src/schemas/options.schema.json
@@ -13,10 +13,14 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "documentationComment": {
+            "interfaceDocumentationComment": {
               "type": "string",
               "description": "This value is placed in a documentation comment for the exported default interface."
             },
+            "valueDocumentationComment": {
+              "type": "string",
+              "description": "This value is placed in a documentation comment for the exported value."
+            },
             "interfaceName": {
               "type": "string",
               "description": "The interface name for the default wrapped export. Defaults to \"IExport\""
@@ -27,10 +31,14 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "documentationComment": {
+            "interfaceDocumentationComment": {
               "type": "string",
               "description": "This value is placed in a documentation comment for the exported default interface."
             },
+            "valueDocumentationComment": {
+              "type": "string",
+              "description": "This value is placed in a documentation comment for the exported value."
+            },
             "inferInterfaceNameFromFilename": {
               "type": "boolean",
               "description": "When set to true, the default export interface name will be inferred from the filename. This takes precedence over the interfaceName option."

diff --git a/libraries/localization-utilities/src/TypingsGenerator.ts b/libraries/localization-utilities/src/TypingsGenerator.ts
@@ -82,8 +82,8 @@ export class TypingsGenerator extends StringValuesTypingsGenerator {
         const typings: IStringValueTyping[] = [];
 
         // eslint-disable-next-line guard-for-in
-        for (const stringName in locFileData) {
-          let comment: string | undefined = locFileData[stringName].comment;
+        for (const [stringName, value] of Object.entries(locFileData)) {
+          let comment: string | undefined = value.comment;
           if (processComment) {
             comment = processComment(comment, relativeFilePath, stringName);
           }

diff --git a/libraries/typings-generator/src/StringValuesTypingsGenerator.ts b/libraries/typings-generator/src/StringValuesTypingsGenerator.ts
@@ -42,11 +42,22 @@ export interface IExportAsDefaultOptions {
    */
   interfaceName?: string;
 
+  /**
+   * @deprecated - Use {@link IExportAsDefaultOptions.interfaceDocumentationComment} instead.
+   */
+  documentationComment?: string;
+
   /**
    * This value is placed in a documentation comment for the
    * exported default interface.
    */
-  documentationComment?: string;
+  interfaceDocumentationComment?: string;
+
+  /**
+   * This value is placed in a documentation comment for the
+   * exported const value.
+   */
+  valueDocumentationComment?: string;
 }
 
 /**
@@ -93,16 +104,22 @@ function convertToTypingsGeneratorOptions<TFileContents>(
     exportAsDefaultInterfaceName: exportAsDefaultInterfaceName_deprecated,
     parseAndGenerateTypings
   } = options;
-  let defaultSplitExportAsDefaultDocumentationComment: string[] | undefined;
+  let defaultSplitExportAsDefaultInterfaceDocumentationComment: string[] | undefined;
+  let defaultSplitExportAsDefaultValueDocumentationComment: string[] | undefined;
   let defaultExportAsDefaultInterfaceName: string | undefined;
   if (typeof exportAsDefaultOptions === 'object') {
-    defaultSplitExportAsDefaultDocumentationComment = Text.splitByNewLines(
-      exportAsDefaultOptions.documentationComment
+    const {
+      interfaceDocumentationComment,
+      documentationComment: interfaceDocumentationComment_deprecated,
+      valueDocumentationComment,
+      interfaceName
+    } = exportAsDefaultOptions;
+    defaultSplitExportAsDefaultInterfaceDocumentationComment = Text.splitByNewLines(
+      interfaceDocumentationComment ?? interfaceDocumentationComment_deprecated
     );
+    defaultSplitExportAsDefaultValueDocumentationComment = Text.splitByNewLines(valueDocumentationComment);
     defaultExportAsDefaultInterfaceName =
-      exportAsDefaultOptions.interfaceName ??
-      exportAsDefaultInterfaceName_deprecated ??
-      EXPORT_AS_DEFAULT_INTERFACE_NAME;
+      interfaceName ?? exportAsDefaultInterfaceName_deprecated ?? EXPORT_AS_DEFAULT_INTERFACE_NAME;
   } else if (exportAsDefaultOptions) {
     defaultExportAsDefaultInterfaceName =
       exportAsDefaultInterfaceName_deprecated ?? EXPORT_AS_DEFAULT_INTERFACE_NAME;
@@ -126,21 +143,34 @@ function convertToTypingsGeneratorOptions<TFileContents>(
     const { exportAsDefault: exportAsDefaultOptionsOverride, typings } = stringValueTypings;
     let exportAsDefaultInterfaceName: string | undefined;
     let interfaceDocumentationCommentLines: string[] | undefined;
+    let valueDocumentationCommentLines: string[] | undefined;
     if (typeof exportAsDefaultOptionsOverride === 'boolean') {
       if (exportAsDefaultOptionsOverride) {
         exportAsDefaultInterfaceName =
           defaultExportAsDefaultInterfaceName ?? EXPORT_AS_DEFAULT_INTERFACE_NAME;
-        interfaceDocumentationCommentLines = defaultSplitExportAsDefaultDocumentationComment;
+        interfaceDocumentationCommentLines = defaultSplitExportAsDefaultInterfaceDocumentationComment;
+        valueDocumentationCommentLines = defaultSplitExportAsDefaultValueDocumentationComment;
       }
     } else if (exportAsDefaultOptionsOverride) {
-      const { interfaceName, documentationComment } = exportAsDefaultOptionsOverride;
+      const {
+        interfaceName,
+        documentationComment,
+        interfaceDocumentationComment,
+        valueDocumentationComment
+      } = exportAsDefaultOptionsOverride;
       exportAsDefaultInterfaceName =
         interfaceName ?? defaultExportAsDefaultInterfaceName ?? EXPORT_AS_DEFAULT_INTERFACE_NAME;
       interfaceDocumentationCommentLines =
-        Text.splitByNewLines(documentationComment) ?? defaultSplitExportAsDefaultDocumentationComment;
+        Text.splitByNewLines(interfaceDocumentationComment) ??
+        Text.splitByNewLines(documentationComment) ??
+        defaultSplitExportAsDefaultInterfaceDocumentationComment;
+      valueDocumentationCommentLines =
+        Text.splitByNewLines(valueDocumentationComment) ??
+        defaultSplitExportAsDefaultValueDocumentationComment;
     } else {
       exportAsDefaultInterfaceName = defaultExportAsDefaultInterfaceName;
-      interfaceDocumentationCommentLines = defaultSplitExportAsDefaultDocumentationComment;
+      interfaceDocumentationCommentLines = defaultSplitExportAsDefaultInterfaceDocumentationComment;
+      valueDocumentationCommentLines = defaultSplitExportAsDefaultValueDocumentationComment;
     }
 
     const outputLines: string[] = [];
@@ -174,9 +204,18 @@ function convertToTypingsGeneratorOptions<TFileContents>(
     }
 
     if (exportAsDefaultInterfaceName) {
+      outputLines.push('}', '');
+
+      if (valueDocumentationCommentLines) {
+        outputLines.push(`/**`);
+        for (const line of valueDocumentationCommentLines) {
+          outputLines.push(` * ${line}`);
+        }
+
+        outputLines.push(` */`);
+      }
+
       outputLines.push(
-        '}',
-        '',
         `declare const strings: ${exportAsDefaultInterfaceName};`,
         '',
         'export default strings;'

diff --git a/libraries/typings-generator/src/test/StringValuesTypingsGenerator.test.ts b/libraries/typings-generator/src/test/StringValuesTypingsGenerator.test.ts
@@ -122,10 +122,20 @@ describe('StringValuesTypingsGenerator', () => {
       });
     });
 
-    describe("with { exportAsDefault: { documentationComment: 'doc-comment\\nsecond line' } }", () => {
+    describe("with { exportAsDefault: documentationComment: 'deprecated', interfaceDocumentationComment: 'doc-comment' }", () => {
       runTests({
         exportAsDefault: {
-          documentationComment: 'doc-comment\nsecond line'
+          documentationComment: 'deprecated',
+          interfaceDocumentationComment: 'doc-comment'
+        }
+      });
+    });
+
+    describe("with { exportAsDefault: { *DocumentationComment: 'doc-comment\\nsecond line' } }", () => {
+      runTests({
+        exportAsDefault: {
+          interfaceDocumentationComment: 'doc-comment\nsecond line',
+          valueDocumentationComment: 'value-comment\nsecond line'
         }
       });
     });
@@ -157,7 +167,8 @@ describe('StringValuesTypingsGenerator', () => {
             {},
             {
               exportAsDefault: {
-                documentationComment: 'doc-comment\nsecond line'
+                interfaceDocumentationComment: 'doc-comment\nsecond line',
+                valueDocumentationComment: 'value-comment\nsecond line'
               }
             }
           );
@@ -196,7 +207,8 @@ describe('StringValuesTypingsGenerator', () => {
             },
             {
               exportAsDefault: {
-                documentationComment: 'doc-comment\nsecond line'
+                interfaceDocumentationComment: 'doc-comment\nsecond line',
+                valueDocumentationComment: 'value-comment\nsecond line'
               }
             }
           );
@@ -235,7 +247,8 @@ describe('StringValuesTypingsGenerator', () => {
             },
             {
               exportAsDefault: {
-                documentationComment: 'doc-comment\nsecond line'
+                interfaceDocumentationComment: 'doc-comment\nsecond line',
+                valueDocumentationComment: 'value-comment\nsecond line'
               }
             }
           );
@@ -248,7 +261,8 @@ describe('StringValuesTypingsGenerator', () => {
             {
               exportAsDefault: {
                 interfaceName: 'IBase',
-                documentationComment: 'base-comment'
+                interfaceDocumentationComment: 'base-comment',
+                valueDocumentationComment: 'base-value-comment'
               }
             },
             {
@@ -262,7 +276,8 @@ describe('StringValuesTypingsGenerator', () => {
             {
               exportAsDefault: {
                 interfaceName: 'IBase',
-                documentationComment: 'base-comment'
+                interfaceDocumentationComment: 'base-comment',
+                valueDocumentationComment: 'base-value-comment'
               }
             },
             {
@@ -278,12 +293,14 @@ describe('StringValuesTypingsGenerator', () => {
             {
               exportAsDefault: {
                 interfaceName: 'IBase',
-                documentationComment: 'base-comment'
+                interfaceDocumentationComment: 'base-comment',
+                valueDocumentationComment: 'base-value-comment'
               }
             },
             {
               exportAsDefault: {
-                documentationComment: 'doc-comment\nsecond line'
+                interfaceDocumentationComment: 'doc-comment\nsecond line',
+                valueDocumentationComment: 'value-comment\nsecond line'
               }
             }
           );