3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 15:47:23 +02:00
Code Issues Projects Releases Packages Wiki Activity

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

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

* fix
This commit is contained in:
Joshua Chen 2022-04-11 09:36:30 +08:00 • committed by GitHub
parent 25ba91fd4d
commit f4ab7c65ac
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 139 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

20
packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts
View file

@ -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
@ -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) =>
@ -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
packages/docusaurus-plugin-content-docs/src/client/index.ts
View file

@ -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
packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts vendored
View file

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