refactor: capitalize comments (#7188)

* refactor: capitalize comments

* revert...

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

@@ -849,7 +849,6 @@ describe('versioned site', () => {
     const {siteDir, context, options, version100} = await loadSite({
       options: {
         editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
-        // editCurrentVersion: true,
       },
     });
 

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

@@ -68,8 +68,8 @@ const createFakeActions = (contentDir: string) => {
     },
   };
 
-  // query by prefix, because files have a hash at the end
-  // so it's not convenient to query by full filename
+  // Query by prefix, because files have a hash at the end so it's not
+  // convenient to query by full filename
   const getCreatedDataByPrefix = (prefix: string) => {
     const entry = Object.entries(dataContainer).find(([key]) =>
       key.startsWith(prefix),

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

@@ -23,7 +23,7 @@ const IgnoredNumberPrefixPatterns = [
   '00abc01-My Doc',
   'My 001- Doc',
   'My -001 Doc',
-  // ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
+  // Ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
   '2021-01-31 - Doc',
   '31-01-2021 - Doc',
   '2021_01_31 - Doc',
@@ -36,7 +36,7 @@ const IgnoredNumberPrefixPatterns = [
   '01-2021 - Doc',
   '01_2021 - Doc',
   '01.2021 - Doc',
-  // date patterns without suffix
+  // Date patterns without suffix
   '2021-01-31',
   '2021-01',
   '21-01-31',
@@ -49,7 +49,7 @@ const IgnoredNumberPrefixPatterns = [
   '01',
   '2021',
   '01',
-  // ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
+  // Ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
   '8.0',
   '8.0.0',
   '14.2.16',

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

@@ -15,7 +15,7 @@ import {
 import {GlobExcludeDefault} from '@docusaurus/utils';
 import type {Options} from '@docusaurus/plugin-content-docs';
 
-// the type of remark/rehype plugins is function
+// The type of remark/rehype plugins can be function/object
 const markdownPluginsFunctionStub = () => {};
 const markdownPluginsObjectStub = {};
 

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

@@ -57,7 +57,7 @@ describe('toTagDocListProp', () => {
       count: 2,
       label: tag.label,
       permalink: tag.permalink,
-      items: [doc3, doc1], // docs sorted by title, ignore "id5" absence
+      items: [doc3, doc1], // Docs sorted by title, ignore "id5" absence
     });
   });
 });

packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts

@@ -226,7 +226,7 @@ describe('docsClientUtils', () => {
       ],
     };
 
-    // shuffle, because order shouldn't matter
+    // Shuffle, because order shouldn't matter
     const versions: GlobalVersion[] = _.shuffle([
       versionNext,
       version2,
@@ -355,7 +355,7 @@ describe('docsClientUtils', () => {
       ],
     };
 
-    // shuffle, because order shouldn't matter
+    // Shuffle, because order shouldn't matter
     const versions: GlobalVersion[] = _.shuffle([
       versionNext,
       version2,
@@ -395,7 +395,7 @@ describe('docsClientUtils', () => {
       latestVersionSuggestion: version2,
     });
     expect(getDocVersionSuggestions(data, '/docs/version1/doc2')).toEqual({
-      latestDocSuggestion: undefined, // because /docs/version1/doc2 does not exist
+      latestDocSuggestion: undefined, // Because /docs/version1/doc2 does not exist
       latestVersionSuggestion: version2,
     });
   });

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

@@ -156,15 +156,13 @@ function doProcessDocMetadata({
     parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
 
-  // ex: api/plugins/myDoc -> myDoc
-  // ex: myDoc -> myDoc
+  // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
   const sourceFileNameWithoutExtension = path.basename(
     source,
     path.extname(source),
   );
 
-  // ex: api/plugins/myDoc -> api/plugins
-  // ex: myDoc -> .
+  // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
   const sourceDirName = path.dirname(source);
 
   const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes
@@ -347,7 +345,7 @@ export function addDocNavigation(
   }
 
   const docsWithNavigation = docsBase.map(addNavData);
-  // sort to ensure consistent output for tests
+  // Sort to ensure consistent output for tests
   docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
   return docsWithNavigation;
 }
@@ -434,7 +432,7 @@ export function getDocIds(doc: DocMetadataBase): [string, string] {
   return [doc.unversionedId, doc.id];
 }
 
-// docs are indexed by both versioned and unversioned ids at the same time
+// Docs are indexed by both versioned and unversioned ids at the same time
 // TODO legacy retro-compatibility due to old versioned sidebars using
 // versioned doc ids ("id" should be removed & "versionedId" should be renamed
 // to "id")

packages/docusaurus-plugin-content-docs/src/frontMatter.ts

@@ -20,12 +20,14 @@ import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 // We use default values in code instead
 const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   id: Joi.string(),
-  title: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  title: Joi.string().allow(''),
   hide_title: Joi.boolean(),
   hide_table_of_contents: Joi.boolean(),
   keywords: Joi.array().items(Joi.string().required()),
   image: URISchema,
-  description: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  description: Joi.string().allow(''),
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -19,7 +19,7 @@ declare module '@docusaurus/plugin-content-docs' {
    * Custom callback for parsing number prefixes from file/folder names.
    */
   export type NumberPrefixParser = (filename: string) => {
-    /** file name without number prefix, without any other modification. */
+    /** File name without number prefix, without any other modification. */
     filename: string;
     /** The number prefix. Can be float, integer, negative, or anything. */
     numberPrefix?: number;
@@ -621,9 +621,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 one exists) */
     latestDocSuggestion?: GlobalDoc;
   };
 

packages/docusaurus-plugin-content-docs/src/routes.ts

@@ -139,11 +139,9 @@ export async function createVersionRoutes({
 
     actions.addRoute({
       path: version.path,
-      // allow matching /docs/* as well
+      // Allow matching /docs/* since this is the wrapping route
       exact: false,
-      // main docs component (DocPage)
       component: docLayoutComponent,
-      // sub-routes for each doc
       routes: await createVersionSubRoutes(),
       modules: {
         versionMetadata: aliasedSource(versionMetadataPropPath),

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

@@ -76,9 +76,9 @@ Available doc IDs:
       return (
         // Doc at the root of the autogenerated sidebar dir
         doc.sourceDirName === autogenDir ||
-        // autogen dir is . and doc is in subfolder
+        // Autogen dir is . and doc is in subfolder
         autogenDir === '.' ||
-        // autogen dir is not . and doc is in subfolder
+        // Autogen dir is not . and doc is in subfolder
         // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
         doc.sourceDirName.startsWith(addTrailingSlash(autogenDir))
       );

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

@@ -22,7 +22,7 @@ function normalizeCategoryLink(
   params: SidebarProcessorParams,
 ): SidebarItemCategoryLink | undefined {
   if (category.link?.type === 'generated-index') {
-    // default slug logic can be improved
+    // Default slug logic can be improved
     const getDefaultSlug = () =>
       `/category/${params.categoryLabelSlugger.slug(category.label)}`;
     const slug = category.link.slug ?? getDefaultSlug();

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

@@ -180,7 +180,6 @@ export type PropSidebarItemCategory = Expand<
   }
 >;
 
-// we may want to use a union type in props instead of this generic link?
 export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
 };
@@ -245,7 +244,7 @@ export type SidebarItemsGeneratorArgs = {
   /** The default category index matcher which you can override. */
   isCategoryIndex: CategoryIndexMatcher;
   /**
-   * key is the path relative to the doc content directory, value is the
+   * Key is the path relative to the doc content directory, value is the
    * category metadata file's content.
    */
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile};

packages/docusaurus-plugin-content-docs/src/translations.ts

@@ -53,50 +53,6 @@ function getNormalizedSidebarName({
   return rest.join('/');
 }
 
-/*
-// Do we need to translate doc metadata?
-// It seems translating front matter labels is good enough
-function getDocTranslations(doc: DocMetadata): TranslationFileContent {
-  return {
-    [`${doc.unversionedId}.title`]: {
-      message: doc.title,
-      description: `The title for doc with id=${doc.unversionedId}`,
-    },
-    ...(doc.sidebar_label
-      ? {
-          [`${doc.unversionedId}.sidebar_label`]: {
-            message: doc.sidebar_label,
-            description:
-              `The sidebar label for doc with id=${doc.unversionedId}`,
-          },
-        }
-      : undefined),
-  };
-}
-function translateDoc(
-  doc: DocMetadata,
-  docsTranslations: TranslationFileContent,
-): DocMetadata {
-  return {
-    ...doc,
-    title: docsTranslations[`${doc.unversionedId}.title`]?.message ?? doc.title,
-    sidebar_label:
-      docsTranslations[`${doc.unversionedId}.sidebar_label`]?.message ??
-      doc.sidebar_label,
-  };
-}
-
-function getDocsTranslations(version: LoadedVersion): TranslationFileContent {
-  return mergeTranslations(version.docs.map(getDocTranslations));
-}
-function translateDocs(
-  docs: DocMetadata[],
-  docsTranslations: TranslationFileContent,
-): DocMetadata[] {
-  return docs.map((doc) => translateDoc(doc, docsTranslations));
-}
- */
-
 function getSidebarTranslationFileContent(
   sidebar: Sidebar,
   sidebarName: string,
@@ -252,17 +208,10 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFile[] {
   const sidebarsTranslations: TranslationFileContent =
     getSidebarsTranslations(version);
 
-  // const docsTranslations: TranslationFileContent =
-  //   getDocsTranslations(version);
-
   return [
     {
       path: getVersionFileName(version.versionName),
-      content: mergeTranslations([
-        versionTranslations,
-        sidebarsTranslations,
-        // docsTranslations,
-      ]),
+      content: mergeTranslations([versionTranslations, sidebarsTranslations]),
     },
   ];
 }
@@ -276,7 +225,6 @@ function translateVersion(
     ...version,
     label: versionTranslations['version.label']?.message ?? version.label,
     sidebars: translateSidebars(version, versionTranslations),
-    // docs: translateDocs(version.docs, versionTranslations),
   };
 }
 

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

@@ -30,7 +30,7 @@ export type SourceToPermalink = {
 };
 
 export type VersionTag = Tag & {
-  /** all doc ids having this tag. */
+  /** All doc ids having this tag. */
   docIds: string[];
 };
 export type VersionTags = {