refactor(content-docs): deduplicate types, JSDoc for some APIs (#7027)

* refactor(content-docs): deduplicate types, JSDoc for some APIs * little refactor
2025-07-31 07:18:59 +02:00 · 2022-03-27 12:57:15 +08:00 · 2022-03-27 12:57:15 +08:00 · 2bcac29cd4
commit 2bcac29cd4
parent b842197ac6
38 changed files with 715 additions and 521 deletions
--- a/packages/docusaurus-plugin-content-docs/src/tests/snapshots/translations.test.ts.snap
+++ b/packages/docusaurus-plugin-content-docs/src/tests/snapshots/translations.test.ts.snap
@ -169,7 +169,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
        },
      ],
      "isLast": true,
+      "label": "current label (translated)",
      "mainDocId": "",
+      "path": "/docs/",
      "routePriority": undefined,
      "sidebarFilePath": "any",
      "sidebars": {
@ -221,9 +223,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
          },
        ],
      },
-      "versionLabel": "current label (translated)",
      "versionName": "current",
-      "versionPath": "/docs/",
    },
    {
      "contentPath": "any",
@ -311,7 +311,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
        },
      ],
      "isLast": true,
+      "label": "2.0.0 label (translated)",
      "mainDocId": "",
+      "path": "/docs/",
      "routePriority": undefined,
      "sidebarFilePath": "any",
      "sidebars": {
@ -363,9 +365,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
          },
        ],
      },
-      "versionLabel": "2.0.0 label (translated)",
      "versionName": "2.0.0",
-      "versionPath": "/docs/",
    },
    {
      "contentPath": "any",
@ -453,7 +453,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
        },
      ],
      "isLast": true,
+      "label": "1.0.0 label (translated)",
      "mainDocId": "",
+      "path": "/docs/",
      "routePriority": undefined,
      "sidebarFilePath": "any",
      "sidebars": {
@ -505,9 +507,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
          },
        ],
      },
-      "versionLabel": "1.0.0 label (translated)",
      "versionName": "1.0.0",
-      "versionPath": "/docs/",
    },
  ],
 }
--- a/packages/docusaurus-plugin-content-docs/src/tests/docs.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/docs.test.ts
@ -18,16 +18,14 @@ import {
 import {loadSidebars} from '../sidebars';
 import type {Sidebars} from '../sidebars/types';
 import {readVersionsMetadata} from '../versions';
-import type {
-  DocFile,
-  DocMetadataBase,
-  VersionMetadata,
-  DocNavLink,
-} from '../types';
+import type {DocFile} from '../types';
 import type {
  MetadataOptions,
  PluginOptions,
  EditUrlFunction,
+  DocMetadataBase,
+  VersionMetadata,
+  PropNavigationLink,
 } from '@docusaurus/plugin-content-docs';
 import type {LoadContext} from '@docusaurus/types';
 import {DEFAULT_OPTIONS} from '../options';
@ -123,7 +121,11 @@ function createTestUtils({
  }

  async function generateNavigation(docFiles: DocFile[]): Promise<{
-    pagination: {prev?: DocNavLink; next?: DocNavLink; id: string}[];
+    pagination: {
+      prev?: PropNavigationLink;
+      next?: PropNavigationLink;
+      id: string;
+    }[];
    sidebars: Sidebars;
  }> {
    const rawDocs = docFiles.map((docFile) =>
--- a/packages/docusaurus-plugin-content-docs/src/tests/frontMatter.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/frontMatter.test.ts
@ -6,7 +6,7 @@
 */

 import {validateDocFrontMatter} from '../frontMatter';
-import type {DocFrontMatter} from '../types';
+import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 import escapeStringRegexp from 'escape-string-regexp';

 function testField(params: {
--- a/packages/docusaurus-plugin-content-docs/src/tests/globalData.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/globalData.test.ts
@ -12,9 +12,9 @@ describe('toGlobalDataVersion', () => {
    expect(
      toGlobalDataVersion({
        versionName: 'current',
-        versionLabel: 'Label',
+        label: 'Label',
        isLast: true,
-        versionPath: '/current',
+        path: '/current',
        mainDocId: 'main',
        docs: [
          {
@ -86,9 +86,9 @@ describe('toGlobalDataVersion', () => {
            sidebar: 'tutorial',
          },
        ],
-        versionBanner: 'unreleased',
-        versionBadge: true,
-        versionClassName: 'current-cls',
+        banner: 'unreleased',
+        badge: true,
+        className: 'current-cls',
        tagsPath: '/current/tags',
        contentPath: '',
        contentPathLocalized: '',
--- a/packages/docusaurus-plugin-content-docs/src/tests/props.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/props.test.ts
@ -16,7 +16,7 @@ describe('toTagDocListProp', () => {

  it('works', () => {
    const tag: Tag = {
-      name: 'tag1',
+      label: 'tag1',
      permalink: '/tag1',
      docIds: ['id1', 'id3'],
    };
@ -54,7 +54,7 @@ describe('toTagDocListProp', () => {

    expect(result).toEqual({
      allTagsPath,
-      name: tag.name,
+      name: tag.label,
      permalink: tag.permalink,
      docs: [doc3, doc1], // docs sorted by title, ignore "id5" absence
    });
--- a/packages/docusaurus-plugin-content-docs/src/tests/translations.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/translations.test.ts
@ -5,12 +5,13 @@
 * LICENSE file in the root directory of this source tree.
 */

-import type {LoadedContent, DocMetadata, LoadedVersion} from '../types';
+import type {LoadedContent, LoadedVersion} from '../types';
 import {CURRENT_VERSION_NAME} from '../constants';
 import {
  getLoadedContentTranslationFiles,
  translateLoadedContent,
 } from '../translations';
+import type {DocMetadata} from '@docusaurus/plugin-content-docs';
 import {updateTranslationFileMessages} from '@docusaurus/utils';

 function createSampleDoc(doc: Pick<DocMetadata, 'id'>): DocMetadata {
@ -36,8 +37,8 @@ function createSampleVersion(
  version: Pick<LoadedVersion, 'versionName'>,
 ): LoadedVersion {
  return {
-    versionLabel: `${version.versionName} label`,
-    versionPath: '/docs/',
+    label: `${version.versionName} label`,
+    path: '/docs/',
    mainDocId: '',
    routePriority: undefined,
    sidebarFilePath: 'any',
@ -45,21 +46,11 @@ function createSampleVersion(
    contentPath: 'any',
    contentPathLocalized: 'any',
    docs: [
-      createSampleDoc({
-        id: 'doc1',
-      }),
-      createSampleDoc({
-        id: 'doc2',
-      }),
-      createSampleDoc({
-        id: 'doc3',
-      }),
-      createSampleDoc({
-        id: 'doc4',
-      }),
-      createSampleDoc({
-        id: 'doc5',
-      }),
+      createSampleDoc({id: 'doc1'}),
+      createSampleDoc({id: 'doc2'}),
+      createSampleDoc({id: 'doc3'}),
+      createSampleDoc({id: 'doc4'}),
+      createSampleDoc({id: 'doc5'}),
    ],
    sidebars: {
      docs: [
--- a/packages/docusaurus-plugin-content-docs/src/tests/versions.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/versions.test.ts
@ -15,9 +15,11 @@ import {
 } from '../versions';
 import {DEFAULT_OPTIONS} from '../options';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
-import type {VersionMetadata} from '../types';
 import type {I18n} from '@docusaurus/types';
-import type {PluginOptions} from '@docusaurus/plugin-content-docs';
+import type {
+  PluginOptions,
+  VersionMetadata,
+} from '@docusaurus/plugin-content-docs';

 const DefaultI18N: I18n = {
  currentLocale: 'en',
@ -85,12 +87,12 @@ describe('readVersionsMetadata', () => {
        routePriority: -1,
        sidebarFilePath: undefined,
        tagsPath: '/docs/tags',
-        versionLabel: 'Next',
+        label: 'Next',
        versionName: 'current',
-        versionPath: '/docs',
-        versionBanner: null,
-        versionBadge: false,
-        versionClassName: 'docs-version-current',
+        path: '/docs',
+        banner: null,
+        badge: false,
+        className: 'docs-version-current',
      };
      return {simpleSiteDir, defaultOptions, defaultContext, vCurrent};
    }
@ -120,7 +122,7 @@ describe('readVersionsMetadata', () => {
      expect(versionsMetadata).toEqual([
        {
          ...vCurrent,
-          versionPath: '/myBaseUrl/docs',
+          path: '/myBaseUrl/docs',
          tagsPath: '/myBaseUrl/docs/tags',
        },
      ]);
@ -148,13 +150,13 @@ describe('readVersionsMetadata', () => {
      expect(versionsMetadata).toEqual([
        {
          ...vCurrent,
-          versionPath: '/myBaseUrl/docs/current-path',
-          versionLabel: 'current-label',
+          path: '/myBaseUrl/docs/current-path',
+          label: 'current-label',
          routePriority: undefined,
          sidebarFilePath: undefined,
          tagsPath: '/myBaseUrl/docs/current-path/tags',
-          versionEditUrl: undefined,
-          versionEditUrlLocalized: undefined,
+          editUrl: undefined,
+          editUrlLocalized: undefined,
        },
      ]);
    });
@ -245,12 +247,12 @@ describe('readVersionsMetadata', () => {
        routePriority: undefined,
        sidebarFilePath: path.join(versionedSiteDir, 'sidebars.json'),
        tagsPath: '/docs/next/tags',
-        versionLabel: 'Next',
+        label: 'Next',
        versionName: 'current',
-        versionPath: '/docs/next',
-        versionBanner: 'unreleased',
-        versionBadge: true,
-        versionClassName: 'docs-version-current',
+        path: '/docs/next',
+        banner: 'unreleased',
+        badge: true,
+        className: 'docs-version-current',
      };

      const v101: VersionMetadata = {
@ -269,12 +271,12 @@ describe('readVersionsMetadata', () => {
          'versioned_sidebars/version-1.0.1-sidebars.json',
        ),
        tagsPath: '/docs/tags',
-        versionLabel: '1.0.1',
+        label: '1.0.1',
        versionName: '1.0.1',
-        versionPath: '/docs',
-        versionBanner: null,
-        versionBadge: true,
-        versionClassName: 'docs-version-1.0.1',
+        path: '/docs',
+        banner: null,
+        badge: true,
+        className: 'docs-version-1.0.1',
      };

      const v100: VersionMetadata = {
@ -293,12 +295,12 @@ describe('readVersionsMetadata', () => {
          'versioned_sidebars/version-1.0.0-sidebars.json',
        ),
        tagsPath: '/docs/1.0.0/tags',
-        versionLabel: '1.0.0',
+        label: '1.0.0',
        versionName: '1.0.0',
-        versionPath: '/docs/1.0.0',
-        versionBanner: 'unmaintained',
-        versionBadge: true,
-        versionClassName: 'docs-version-1.0.0',
+        path: '/docs/1.0.0',
+        banner: 'unmaintained',
+        badge: true,
+        className: 'docs-version-1.0.0',
      };

      const vWithSlugs: VersionMetadata = {
@ -317,12 +319,12 @@ describe('readVersionsMetadata', () => {
          'versioned_sidebars/version-withSlugs-sidebars.json',
        ),
        tagsPath: '/docs/withSlugs/tags',
-        versionLabel: 'withSlugs',
+        label: 'withSlugs',
        versionName: 'withSlugs',
-        versionPath: '/docs/withSlugs',
-        versionBanner: 'unmaintained',
-        versionBadge: true,
-        versionClassName: 'docs-version-withSlugs',
+        path: '/docs/withSlugs',
+        banner: 'unmaintained',
+        badge: true,
+        className: 'docs-version-withSlugs',
      };

      return {
@ -393,27 +395,27 @@ describe('readVersionsMetadata', () => {
        {
          ...vCurrent,
          tagsPath: '/docs/current-path/tags',
-          versionPath: '/docs/current-path',
-          versionBanner: 'unmaintained',
-          versionBadge: false,
-          versionClassName: 'custom-current-className',
+          path: '/docs/current-path',
+          banner: 'unmaintained',
+          badge: false,
+          className: 'custom-current-className',
        },
        {
          ...v101,
          isLast: false,
          routePriority: undefined,
          tagsPath: '/docs/1.0.1/tags',
-          versionPath: '/docs/1.0.1',
-          versionBanner: 'unreleased',
+          path: '/docs/1.0.1',
+          banner: 'unreleased',
        },
        {
          ...v100,
          isLast: true,
          routePriority: -1,
          tagsPath: '/docs/tags',
-          versionLabel: '1.0.0-label',
-          versionPath: '/docs',
-          versionBanner: 'unreleased',
+          label: '1.0.0-label',
+          path: '/docs',
+          banner: 'unreleased',
        },
        vWithSlugs,
      ]);
@ -434,30 +436,30 @@ describe('readVersionsMetadata', () => {
      expect(versionsMetadata).toEqual([
        {
          ...vCurrent,
-          versionEditUrl:
+          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/docs',
-          versionEditUrlLocalized:
+          editUrlLocalized:
            'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
        },
        {
          ...v101,
-          versionEditUrl:
+          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.1',
-          versionEditUrlLocalized:
+          editUrlLocalized:
            'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.1',
        },
        {
          ...v100,
-          versionEditUrl:
+          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.0',
-          versionEditUrlLocalized:
+          editUrlLocalized:
            'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.0',
        },
        {
          ...vWithSlugs,
-          versionEditUrl:
+          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-withSlugs',
-          versionEditUrlLocalized:
+          editUrlLocalized:
            'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-withSlugs',
        },
      ]);
@ -479,30 +481,30 @@ describe('readVersionsMetadata', () => {
      expect(versionsMetadata).toEqual([
        {
          ...vCurrent,
-          versionEditUrl:
+          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/docs',
-          versionEditUrlLocalized:
+          editUrlLocalized:
            'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
        },
        {
          ...v101,
-          versionEditUrl:
+          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/docs',
-          versionEditUrlLocalized:
+          editUrlLocalized:
            'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
        },
        {
          ...v100,
-          versionEditUrl:
+          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/docs',
-          versionEditUrlLocalized:
+          editUrlLocalized:
            'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
        },
        {
          ...vWithSlugs,
-          versionEditUrl:
+          editUrl:
            'https://github.com/facebook/docusaurus/edit/main/website/docs',
-          versionEditUrlLocalized:
+          editUrlLocalized:
            'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
        },
      ]);
@ -538,9 +540,9 @@ describe('readVersionsMetadata', () => {
          isLast: true,
          routePriority: -1,
          tagsPath: '/docs/tags',
-          versionPath: '/docs',
-          versionBanner: null,
-          versionBadge: false,
+          path: '/docs',
+          banner: null,
+          badge: false,
        },
      ]);
    });
@ -679,12 +681,12 @@ describe('readVersionsMetadata', () => {
        routePriority: undefined,
        sidebarFilePath: path.join(versionedSiteDir, 'sidebars.json'),
        tagsPath: '/communityBasePath/next/tags',
-        versionLabel: 'Next',
+        label: 'Next',
        versionName: 'current',
-        versionPath: '/communityBasePath/next',
-        versionBanner: 'unreleased',
-        versionBadge: true,
-        versionClassName: 'docs-version-current',
+        path: '/communityBasePath/next',
+        banner: 'unreleased',
+        badge: true,
+        className: 'docs-version-current',
      };

      const v100: VersionMetadata = {
@ -703,12 +705,12 @@ describe('readVersionsMetadata', () => {
          'community_versioned_sidebars/version-1.0.0-sidebars.json',
        ),
        tagsPath: '/communityBasePath/tags',
-        versionLabel: '1.0.0',
+        label: '1.0.0',
        versionName: '1.0.0',
-        versionPath: '/communityBasePath',
-        versionBanner: null,
-        versionBadge: true,
-        versionClassName: 'docs-version-1.0.0',
+        path: '/communityBasePath',
+        banner: null,
+        badge: true,
+        className: 'docs-version-1.0.0',
      };

      return {versionedSiteDir, defaultOptions, defaultContext, vCurrent, v100};
@ -735,7 +737,7 @@ describe('readVersionsMetadata', () => {

      expect(versionsMetadata).toEqual([
        // vCurrent removed
-        {...v100, versionBadge: false},
+        {...v100, badge: false},
      ]);
    });

@ -753,9 +755,9 @@ describe('readVersionsMetadata', () => {
          isLast: true,
          routePriority: -1,
          tagsPath: '/communityBasePath/tags',
-          versionPath: '/communityBasePath',
-          versionBanner: null,
-          versionBadge: false,
+          path: '/communityBasePath',
+          banner: null,
+          badge: false,
        },
      ]);
    });