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

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

* little refactor

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/postProcessor.test.ts

@@ -34,7 +34,7 @@ describe('postProcess', () => {
       },
       {
         sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: true},
-        version: {versionPath: 'version'},
+        version: {path: 'version'},
       },
     );
 
@@ -53,7 +53,7 @@ describe('postProcess', () => {
         },
         {
           sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: true},
-          version: {versionPath: 'version'},
+          version: {path: 'version'},
         },
       );
     }).toThrowErrorMatchingInlineSnapshot(
@@ -78,7 +78,7 @@ describe('postProcess', () => {
 
         {
           sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: true},
-          version: {versionPath: 'version'},
+          version: {path: 'version'},
         },
       ),
     ).toMatchSnapshot();
@@ -98,7 +98,7 @@ describe('postProcess', () => {
 
         {
           sidebarOptions: {sidebarCollapsed: false, sidebarCollapsible: false},
-          version: {versionPath: 'version'},
+          version: {path: 'version'},
         },
       ),
     ).toMatchSnapshot();
@@ -117,7 +117,7 @@ describe('postProcess', () => {
 
         {
           sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: false},
-          version: {versionPath: 'version'},
+          version: {path: 'version'},
         },
       ),
     ).toMatchSnapshot();

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts

@@ -18,7 +18,7 @@ import type {
 } from '../types';
 import {DefaultSidebarItemsGenerator} from '../generator';
 import {createSlugger} from '@docusaurus/utils';
-import type {VersionMetadata} from '../../types';
+import type {VersionMetadata} from '@docusaurus/plugin-content-docs';
 import {DefaultNumberPrefixParser} from '../../numberPrefix';
 import {isCategoryIndex} from '../../docs';
 

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/utils.test.ts

@@ -16,7 +16,10 @@ import {
   toNavigationLink,
 } from '../utils';
 import type {Sidebar, Sidebars} from '../types';
-import type {DocMetadataBase, DocNavLink} from '../../types';
+import type {
+  DocMetadataBase,
+  PropNavigationLink,
+} from '@docusaurus/plugin-content-docs';
 
 describe('createSidebarsUtils', () => {
   const sidebar1: Sidebar = [
@@ -618,7 +621,7 @@ describe('toDocNavigationLink', () => {
     ).toEqual({
       title: 'Doc Title',
       permalink: '/docPermalink',
-    } as DocNavLink);
+    } as PropNavigationLink);
   });
 
   it('with pagination_label front matter', () => {
@@ -635,7 +638,7 @@ describe('toDocNavigationLink', () => {
     ).toEqual({
       title: 'pagination_label',
       permalink: '/docPermalink',
-    } as DocNavLink);
+    } as PropNavigationLink);
   });
 
   it('with sidebar_label front matter', () => {
@@ -652,7 +655,7 @@ describe('toDocNavigationLink', () => {
     ).toEqual({
       title: 'sidebar_label',
       permalink: '/docPermalink',
-    } as DocNavLink);
+    } as PropNavigationLink);
   });
 
   it('with pagination_label + sidebar_label front matter', () => {
@@ -670,7 +673,7 @@ describe('toDocNavigationLink', () => {
     ).toEqual({
       title: 'pagination_label',
       permalink: '/docPermalink',
-    } as DocNavLink);
+    } as PropNavigationLink);
   });
 });
 

packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts

@@ -26,7 +26,7 @@ function normalizeCategoryLink(
     const getDefaultSlug = () =>
       `/category/${params.categoryLabelSlugger.slug(category.label)}`;
     const slug = category.link.slug ?? getDefaultSlug();
-    const permalink = normalizeUrl([params.version.versionPath, slug]);
+    const permalink = normalizeUrl([params.version.path, slug]);
     return {
       ...category.link,
       slug,

packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts

@@ -5,7 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {DocMetadataBase, VersionMetadata} from '../types';
+import type {
+  DocMetadataBase,
+  VersionMetadata,
+} from '@docusaurus/plugin-content-docs';
 import type {
   NormalizedSidebarItem,
   NormalizedSidebar,

packages/docusaurus-plugin-content-docs/src/sidebars/types.ts

@@ -6,11 +6,12 @@
  */
 
 import type {Optional, Required} from 'utility-types';
-import type {DocMetadataBase, VersionMetadata} from '../types';
 import type {
   NumberPrefixParser,
   SidebarOptions,
   CategoryIndexMatcher,
+  DocMetadataBase,
+  VersionMetadata,
 } from '@docusaurus/plugin-content-docs';
 import type {Slugger} from '@docusaurus/utils';
 
@@ -199,16 +200,6 @@ export type PropSidebarBreadcrumbsItem =
   | PropSidebarItemLink
   | PropSidebarItemCategory;
 
-export type PropVersionDoc = {
-  id: string;
-  title: string;
-  description?: string;
-  sidebar?: string;
-};
-export type PropVersionDocs = {
-  [docId: string]: PropVersionDoc;
-};
-
 export type CategoryMetadataFile = {
   label?: string;
   position?: number;
@@ -243,11 +234,20 @@ export type SidebarItemsGeneratorVersion = Pick<
 >;
 
 export type SidebarItemsGeneratorArgs = {
+  /** The sidebar item with type "autogenerated" to be transformed. */
   item: SidebarItemAutogenerated;
+  /** Useful metadata for the version this sidebar belongs to. */
   version: SidebarItemsGeneratorVersion;
+  /** All the docs of that version (unfiltered). */
   docs: SidebarItemsGeneratorDoc[];
+  /** Number prefix parser configured for this plugin. */
   numberPrefixParser: NumberPrefixParser;
+  /** The default category index matcher which you can override. */
   isCategoryIndex: CategoryIndexMatcher;
+  /**
+   * key is the path relative to the doc content directory, value is the
+   * category metadata file's content.
+   */
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile};
 };
 export type SidebarItemsGenerator = (
@@ -258,6 +258,10 @@ export type SidebarItemsGenerator = (
 // default sidebar gen logic
 // see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
 export type SidebarItemsGeneratorOptionArgs = {
+  /**
+   * Useful to re-use/enhance the default sidebar generation logic from
+   * Docusaurus.
+   */
   defaultSidebarItemsGenerator: SidebarItemsGenerator;
 } & SidebarItemsGeneratorArgs;
 export type SidebarItemsGeneratorOption = (

packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts

@@ -21,7 +21,10 @@ import type {
 
 import _ from 'lodash';
 import {toMessageRelativeFilePath} from '@docusaurus/utils';
-import type {DocMetadataBase, DocNavLink} from '../types';
+import type {
+  DocMetadataBase,
+  PropNavigationLink,
+} from '@docusaurus/plugin-content-docs';
 
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
@@ -346,7 +349,7 @@ Available document ids are:
   };
 }
 
-export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
+export function toDocNavigationLink(doc: DocMetadataBase): PropNavigationLink {
   const {
     title,
     permalink,
@@ -361,7 +364,7 @@ export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
 export function toNavigationLink(
   navigationItem: SidebarNavigationItem | undefined,
   docsById: {[docId: string]: DocMetadataBase},
-): DocNavLink | undefined {
+): PropNavigationLink | undefined {
   function getDocById(docId: string) {
     const doc = docsById[docId];
     if (!doc) {