[loc-typings] Add an option to generate a doc comment on the exported value.

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
+              }
             }
           }
         },

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 {

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 */

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);

common/changes/@rushstack/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"
+}

common/changes/@rushstack/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"
+}

common/changes/@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"
+}

common/changes/@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"
+}

common/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"
+}

common/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"
+}

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)

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": [
     {

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."

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);
           }

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,11 +104,15 @@ 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
+    defaultSplitExportAsDefaultInterfaceDocumentationComment = Text.splitByNewLines(
+      exportAsDefaultOptions.interfaceDocumentationComment ?? exportAsDefaultOptions.documentationComment
+    );
+    defaultSplitExportAsDefaultValueDocumentationComment = Text.splitByNewLines(
+      exportAsDefaultOptions.valueDocumentationComment
     );
     defaultExportAsDefaultInterfaceName =
       exportAsDefaultOptions.interfaceName ??
@@ -126,21 +141,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 +202,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;'

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'
               }
             }
           );