feat(preset-classic, content-docs/client): JSDoc (#7148)

* refactor: add JSDoc for preset-classic, content-docs/client

* fix

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -12,6 +12,14 @@
 /// <reference types="@docusaurus/plugin-content-blog" />
 /// <reference types="@docusaurus/plugin-content-pages" />
 
+// This file, like all the other ambient declaration files for plugins, is
+// needed for TS to understand our `@theme` alias. The export signatures are
+// duplicated from the implementation, which is fine, since every module only
+// default-exports a React component.
+// TODO we'll eventually migrate to TS `paths` option. This is not easy due to
+// our theme shadowing—we probably need the user to specify multiple theme paths
+// in their tsconfig.
+
 declare module '@docusaurus/theme-classic' {
   export type Options = {
     customCss?: string | string[];
@@ -188,6 +196,40 @@ declare module '@theme/DocItemFooter' {
   export default function DocItemFooter(props: Props): JSX.Element;
 }
 
+declare module '@theme/DocPage/Layout' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+
+  export default function DocPageLayout(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocPage/Layout/Aside' {
+  import type {Dispatch, SetStateAction} from 'react';
+  import type {PropSidebar} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly sidebar: PropSidebar;
+    readonly hiddenSidebarContainer: boolean;
+    readonly setHiddenSidebarContainer: Dispatch<SetStateAction<boolean>>;
+  }
+
+  export default function DocPageLayoutAside(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocPage/Layout/Main' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly hiddenSidebarContainer: boolean;
+    readonly children: ReactNode;
+  }
+
+  export default function DocPageLayoutMain(props: Props): JSX.Element;
+}
+
 declare module '@theme/DocPaginator' {
   import type {PropNavigation} from '@docusaurus/plugin-content-docs';
 
@@ -242,7 +284,7 @@ declare module '@theme/DocSidebar/Desktop/Content' {
 
 declare module '@theme/DocSidebar/Desktop/CollapseButton' {
   export interface Props {
-    onClick: React.MouseEventHandler;
+    readonly onClick: React.MouseEventHandler;
   }
 
   export default function CollapseButton(props: Props): JSX.Element;
@@ -269,7 +311,7 @@ declare module '@theme/DocSidebarItem/Link' {
   import type {PropSidebarItemLink} from '@docusaurus/plugin-content-docs';
 
   export interface Props extends DocSidebarItemProps {
-    item: PropSidebarItemLink;
+    readonly item: PropSidebarItemLink;
   }
 
   export default function DocSidebarItemLink(props: Props): JSX.Element;
@@ -280,7 +322,7 @@ declare module '@theme/DocSidebarItem/Html' {
   import type {PropSidebarItemHtml} from '@docusaurus/plugin-content-docs';
 
   export interface Props extends DocSidebarItemProps {
-    item: PropSidebarItemHtml;
+    readonly item: PropSidebarItemHtml;
   }
 
   export default function DocSidebarItemHtml(props: Props): JSX.Element;
@@ -291,7 +333,7 @@ declare module '@theme/DocSidebarItem/Category' {
   import type {PropSidebarItemCategory} from '@docusaurus/plugin-content-docs';
 
   export interface Props extends DocSidebarItemProps {
-    item: PropSidebarItemCategory;
+    readonly item: PropSidebarItemCategory;
   }
 
   export default function DocSidebarItemCategory(props: Props): JSX.Element;
@@ -350,7 +392,7 @@ declare module '@theme/Footer/Logo' {
   import type {FooterLogo} from '@docusaurus/theme-common';
 
   export interface Props {
-    logo: FooterLogo;
+    readonly logo: FooterLogo;
   }
 
   export default function FooterLogo(props: Props): JSX.Element;
@@ -358,7 +400,7 @@ declare module '@theme/Footer/Logo' {
 
 declare module '@theme/Footer/Copyright' {
   export interface Props {
-    copyright: string;
+    readonly copyright: string;
   }
 
   export default function FooterCopyright(props: Props): JSX.Element;
@@ -368,7 +410,7 @@ declare module '@theme/Footer/LinkItem' {
   import type {FooterLinkItem} from '@docusaurus/theme-common';
 
   export interface Props {
-    item: FooterLinkItem;
+    readonly item: FooterLinkItem;
   }
 
   export default function FooterLinkItem(props: Props): JSX.Element;
@@ -378,10 +420,10 @@ declare module '@theme/Footer/Layout' {
   import type {ReactNode} from 'react';
 
   export interface Props {
-    style: 'light' | 'dark';
-    links: ReactNode;
-    logo: ReactNode;
-    copyright: ReactNode;
+    readonly style: 'light' | 'dark';
+    readonly links: ReactNode;
+    readonly logo: ReactNode;
+    readonly copyright: ReactNode;
   }
 
   export default function FooterLayout(props: Props): JSX.Element;
@@ -391,7 +433,7 @@ declare module '@theme/Footer/Links' {
   import type {Footer} from '@docusaurus/theme-common';
 
   export interface Props {
-    links: Footer['links'];
+    readonly links: Footer['links'];
   }
 
   export default function FooterLinks(props: Props): JSX.Element;
@@ -401,7 +443,7 @@ declare module '@theme/Footer/Links/MultiColumn' {
   import type {MultiColumnFooter} from '@docusaurus/theme-common';
 
   export interface Props {
-    columns: MultiColumnFooter['links'];
+    readonly columns: MultiColumnFooter['links'];
   }
 
   export default function FooterLinksMultiColumn(props: Props): JSX.Element;
@@ -411,7 +453,7 @@ declare module '@theme/Footer/Links/Simple' {
   import type {SimpleFooter} from '@docusaurus/theme-common';
 
   export interface Props {
-    links: SimpleFooter['links'];
+    readonly links: SimpleFooter['links'];
   }
 
   export default function FooterLinksSimple(props: Props): JSX.Element;
@@ -423,7 +465,7 @@ declare module '@theme/Heading' {
   type HeadingType = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 
   export interface Props extends ComponentProps<HeadingType> {
-    as: HeadingType;
+    readonly as: HeadingType;
   }
 
   export default function Heading(props: Props): JSX.Element;
@@ -625,9 +667,9 @@ declare module '@theme/Navbar/MobileSidebar/Layout' {
   import type {ReactNode} from 'react';
 
   interface Props {
-    header: ReactNode;
-    primaryMenu: ReactNode;
-    secondaryMenu: ReactNode;
+    readonly header: ReactNode;
+    readonly primaryMenu: ReactNode;
+    readonly secondaryMenu: ReactNode;
   }
 
   export default function NavbarMobileSidebarLayout(props: Props): JSX.Element;

packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx

@@ -34,7 +34,7 @@ function extractDocRouteMetadata(props: Props): null | {
     versionMetadata,
     location,
   } = props;
-  const currentDocRoute = docRoutes.find((docRoute) =>
+  const currentDocRoute = docRoutes!.find((docRoute) =>
     matchPath(location.pathname, docRoute),
   );
   if (!currentDocRoute) {