Skip to content

Commit

Permalink
feat(preset-classic, content-docs/client): JSDoc (#7148)
Browse files Browse the repository at this point in the history 
* refactor: add JSDoc for preset-classic, content-docs/client

* fix
  • Loading branch information
@Josh-Cena
Josh-Cena committed Apr 11, 2022
1 parent 25ba91f commit f4ab7c6
Show file tree
Hide file tree
Showing 7 changed files with 139 additions and 111 deletions.
20 changes: 9 additions & 11 deletions packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts
View file
Expand Up @@ -59,12 +59,10 @@ export function getActivePlugin(
export const getLatestVersion = (data: GlobalPluginData): GlobalVersion =>
data.versions.find((version) => version.isLast)!;

// Note: return undefined on doc-unrelated pages,
// because there's no version currently considered as active
export const getActiveVersion = (
export function getActiveVersion(
data: GlobalPluginData,
pathname: string,
): GlobalVersion | undefined => {
): GlobalVersion | undefined {
const lastVersion = getLatestVersion(data);
// Last version is a route like /docs/*,
// we need to match it last or it would match /docs/version-1.0/* as well
Expand All @@ -80,12 +78,12 @@ export const getActiveVersion = (
strict: false,
}),
);
};
}

export const getActiveDocContext = (
export function getActiveDocContext(
data: GlobalPluginData,
pathname: string,
): ActiveDocContext => {
): ActiveDocContext {
const activeVersion = getActiveVersion(data, pathname);
const activeDoc = activeVersion?.docs.find(
(doc) =>
Expand Down Expand Up @@ -119,15 +117,15 @@ export const getActiveDocContext = (
activeDoc,
alternateDocVersions: alternateVersionDocs,
};
};
}

export const getDocVersionSuggestions = (
export function getDocVersionSuggestions(
data: GlobalPluginData,
pathname: string,
): DocVersionSuggestions => {
): DocVersionSuggestions {
const latestVersion = getLatestVersion(data);
const activeDocContext = getActiveDocContext(data, pathname);
const latestDocSuggestion: GlobalDoc | undefined =
activeDocContext?.alternateDocVersions[latestVersion.name];
return {latestDocSuggestion, latestVersionSuggestion: latestVersion};
};
}
60 changes: 27 additions & 33 deletions packages/docusaurus-plugin-content-docs/src/client/index.ts
View file
Expand Up @@ -43,67 +43,61 @@ export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
}) as GlobalPluginData;

// TODO this feature should be provided by docusaurus core
export const useActivePlugin = (
export function useActivePlugin(
options: UseDataOptions = {},
): ActivePlugin | undefined => {
): ActivePlugin | undefined {
const data = useAllDocsData();
const {pathname} = useLocation();
return getActivePlugin(data, pathname, options);
};
}

export const useActivePluginAndVersion = (
export function useActivePluginAndVersion(
options: UseDataOptions = {},
):
| undefined
| {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined} => {
| {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined}
| undefined {
const activePlugin = useActivePlugin(options);
const {pathname} = useLocation();
if (activePlugin) {
const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
return {
activePlugin,
activeVersion,
};
if (!activePlugin) {
return undefined;
}
return undefined;
};
const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
return {
activePlugin,
activeVersion,
};
}

// versions are returned ordered (most recent first)
export const useVersions = (pluginId: string | undefined): GlobalVersion[] => {
export function useVersions(pluginId: string | undefined): GlobalVersion[] {
const data = useDocsData(pluginId);
return data.versions;
};
}

export const useLatestVersion = (
pluginId: string | undefined,
): GlobalVersion => {
export function useLatestVersion(pluginId: string | undefined): GlobalVersion {
const data = useDocsData(pluginId);
return getLatestVersion(data);
};
}

// Note: return undefined on doc-unrelated pages,
// because there's no version currently considered as active
export const useActiveVersion = (
export function useActiveVersion(
pluginId: string | undefined,
): GlobalVersion | undefined => {
): GlobalVersion | undefined {
const data = useDocsData(pluginId);
const {pathname} = useLocation();
return getActiveVersion(data, pathname);
};
}

export const useActiveDocContext = (
export function useActiveDocContext(
pluginId: string | undefined,
): ActiveDocContext => {
): ActiveDocContext {
const data = useDocsData(pluginId);
const {pathname} = useLocation();
return getActiveDocContext(data, pathname);
};
}

// Useful to say "hey, you are not on the latest docs version, please switch"
export const useDocVersionSuggestions = (
export function useDocVersionSuggestions(
pluginId: string | undefined,
): DocVersionSuggestions => {
): DocVersionSuggestions {
const data = useDocsData(pluginId);
const {pathname} = useLocation();
return getDocVersionSuggestions(data, pathname);
};
}
68 changes: 22 additions & 46 deletions packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts
View file
Expand Up @@ -554,56 +554,18 @@ declare module '@theme/DocBreadcrumbs' {

declare module '@theme/DocPage' {
import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
import type {DocumentRoute} from '@theme/DocItem';
import type {RouteConfigComponentProps} from 'react-router-config';
import type {Required} from 'utility-types';

export interface Props {
readonly location: {readonly pathname: string};
export interface Props extends Required<RouteConfigComponentProps, 'route'> {
readonly versionMetadata: PropVersionMetadata;
readonly route: {
readonly path: string;
readonly component: () => JSX.Element;
readonly routes: DocumentRoute[];
};
}

export default function DocPage(props: Props): JSX.Element;
}

declare module '@theme/DocPage/Layout' {
import type {ReactNode} from 'react';

export interface Props {
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 {
sidebar: PropSidebar;
hiddenSidebarContainer: boolean;
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 {
hiddenSidebarContainer: boolean;
children: ReactNode;
}

export default function DocPageLayoutMain(props: Props): JSX.Element;
}

// TODO until TS supports exports field... hope it's in 4.6
// TODO TS only supports reading `exports` in 4.7. We will need to merge the
// type defs (and JSDoc) here with the implementation after that
declare module '@docusaurus/plugin-content-docs/client' {
import type {UseDataOptions} from '@docusaurus/types';

Expand All @@ -617,6 +579,11 @@ declare module '@docusaurus/plugin-content-docs/client' {
alternateDocVersions: {[versionName: string]: GlobalDoc};
};
export type GlobalDoc = {
/**
* For generated index pages, this is the `slug`, **not** `permalink`
* (without base URL). Because slugs have leading slashes but IDs don't,
* there won't be clashes.
*/
id: string;
path: string;
sidebar: string | undefined;
Expand All @@ -627,7 +594,8 @@ declare module '@docusaurus/plugin-content-docs/client' {
label: string;
isLast: boolean;
path: string;
mainDocId: string; // home doc (if docs homepage configured), or first doc
/** The doc with `slug: /`, or first doc in first sidebar */
mainDocId: string;
docs: GlobalDoc[];
sidebars?: {[sidebarId: string]: GlobalSidebar};
};
Expand All @@ -645,9 +613,9 @@ declare module '@docusaurus/plugin-content-docs/client' {
breadcrumbs: boolean;
};
export type DocVersionSuggestions = {
// suggest the latest version
/** suggest the latest version */
latestVersionSuggestion: GlobalVersion;
// suggest the same doc, in latest version (if exist)
/** suggest the same doc, in latest version (if exist) */
latestDocSuggestion?: GlobalDoc;
};

Expand All @@ -661,12 +629,20 @@ declare module '@docusaurus/plugin-content-docs/client' {
) =>
| {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined}
| undefined;
/** Versions are returned ordered (most recent first). */
export const useVersions: (pluginId?: string) => GlobalVersion[];
export const useLatestVersion: (pluginId?: string) => GlobalVersion;
/**
* Returns `undefined` on doc-unrelated pages, because there's no version
* currently considered as active.
*/
export const useActiveVersion: (
pluginId?: string,
) => GlobalVersion | undefined;
export const useActiveDocContext: (pluginId?: string) => ActiveDocContext;
/**
* Useful to say "hey, you are not on the latest docs version, please switch"
*/
export const useDocVersionSuggestions: (
pluginId?: string,
) => DocVersionSuggestions;
Expand Down
17 changes: 17 additions & 0 deletions packages/docusaurus-preset-classic/src/preset-classic.d.ts
View file
Expand Up @@ -17,13 +17,30 @@ import type {UserThemeConfig as ClassicThemeConfig} from '@docusaurus/theme-comm
import type {UserThemeConfig as AlgoliaThemeConfig} from '@docusaurus/theme-search-algolia';

export type Options = {
/**
* Options for `@docusaurus/plugin-debug`. Use `false` to disable, or `true`
* to enable even in production.
*/
debug?: boolean;
/** Options for `@docusaurus/plugin-content-docs`. Use `false` to disable. */
docs?: false | DocsPluginOptions;
/** Options for `@docusaurus/plugin-content-blog`. Use `false` to disable. */
blog?: false | BlogPluginOptions;
/** Options for `@docusaurus/plugin-content-pages`. Use `false` to disable. */
pages?: false | PagesPluginOptions;
/** Options for `@docusaurus/plugin-sitemap`. Use `false` to disable. */
sitemap?: false | SitemapPluginOptions;
/** Options for `@docusaurus/theme-classic`. */
theme?: ThemeOptions;
/**
* Options for `@docusaurus/plugin-google-analytics`. Only enabled when the
* key is present.
*/
googleAnalytics?: GAPluginOptions;
/**
* Options for `@docusaurus/plugin-google-gtag`. Only enabled when the key
* is present.
*/
gtag?: GtagPluginOptions;
};

Expand Down

0 comments on commit f4ab7c6

Please sign in to comment.