refactor: capitalize comments (#7188)

* refactor: capitalize comments

* revert...

admin/new.docusaurus.io/functionUtils/playgroundUtils.ts

@@ -16,9 +16,12 @@ const PlaygroundConfigs = {
   codesandbox:
     'https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/classic',
 
-  // stackblitz: 'https://stackblitz.com/fork/docusaurus', // not updated
-  // stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic', // slow to load
-  stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/starter', // dedicated branch: faster load
+  // Not updated
+  // stackblitz: 'https://stackblitz.com/fork/docusaurus',
+  // Slow to load
+  // stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic',
+  // Dedicated branch: faster load
+  stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/starter',
 };
 
 const PlaygroundDocumentationUrl = 'https://docusaurus.io/docs/playground';

admin/scripts/generateExamples.mjs

@@ -24,27 +24,26 @@ async function generateTemplateExample(template) {
       `generating ${template} template for codesandbox in the examples folder...`,
     );
 
-    // run the docusaurus script to create the template in the examples folder
+    // Run the docusaurus script to create the template in the examples folder
     const command = template.endsWith('-typescript')
       ? template.replace('-typescript', ' -- --typescript')
       : template;
     shell.exec(
-      // /!\ we use the published init script on purpose,
-      // because using the local init script is too early and could generate
-      // upcoming/unavailable config options. Remember CodeSandbox templates
-      // will use the published version, not the repo version
+      // We use the published init script on purpose, because the local init is
+      // too new and could generate upcoming/unavailable config options.
+      // Remember CodeSandbox templates will use the published version,
+      // not the repo version.
       `npm init docusaurus@latest examples/${template} ${command}`,
     );
 
-    // read the content of the package.json
     const templatePackageJson = await fs.readJSON(
       `examples/${template}/package.json`,
     );
 
-    // attach the dev script which would be used in code sandbox by default
+    // Attach the dev script which would be used in code sandbox by default
     templatePackageJson.scripts.dev = 'docusaurus start';
 
-    // these example projects are not meant to be published to npm
+    // These example projects are not meant to be published to npm
     templatePackageJson.private = true;
 
     // Make sure package.json name is not "examples-classic". The package.json
@@ -58,13 +57,12 @@ async function generateTemplateExample(template) {
         ? 'Docusaurus example project'
         : `Docusaurus example project (${template} template)`;
 
-    // rewrite the package.json file with the new edit
     await fs.writeFile(
       `./examples/${template}/package.json`,
       `${JSON.stringify(templatePackageJson, null, 2)}\n`,
     );
 
-    // create sandbox.config.json file at the root of template
+    // Create sandbox/stackblitz config file at the root of template
     const codeSandboxConfig = {
       infiniteLoopProtection: true,
       hardReloadOnChange: true,
@@ -162,15 +160,15 @@ console.log(`
 # Generate examples start!
 `);
 
-// delete the examples directories if they exists
+// Delete the examples directories if they exist
 console.log(`-------
 ## Removing example folders...
 `);
 await fs.rm('./examples/classic', {recursive: true, force: true});
 await fs.rm('./examples/classic-typescript', {recursive: true, force: true});
 await fs.rm('./examples/facebook', {recursive: true, force: true});
 
-// get the list of all available templates
+// Get the list of all available templates
 console.log(`
 -------
 ## Generate example folders...
@@ -187,7 +185,7 @@ console.log('Committing changes');
 shell.exec('git add examples');
 shell.exec("git commit -am 'update examples' --allow-empty");
 
-// update starters
+// Update starters
 console.log(`
 -------
 # Updating starter repos and branches ...

jest/snapshotPathNormalizer.ts

@@ -90,23 +90,23 @@ function normalizePaths<T>(value: T): T {
     (val) => val.split(homeDirReal).join('<HOME_DIR>'),
     (val) => val.split(homeDir).join('<HOME_DIR>'),
 
-    // handle HOME_DIR nested inside TEMP_DIR
+    // Handle HOME_DIR nested inside TEMP_DIR
     (val) =>
       val
         .split(`<TEMP_DIR>${path.sep + homeRelativeToTemp}`)
         .join('<HOME_DIR>'),
     (val) =>
       val
         .split(`<TEMP_DIR>${path.sep + homeRelativeToTempReal}`)
-        .join('<HOME_DIR>'), // untested
+        .join('<HOME_DIR>'),
     (val) =>
       val
         .split(`<TEMP_DIR>${path.sep + homeRealRelativeToTempReal}`)
         .join('<HOME_DIR>'),
     (val) =>
       val
         .split(`<TEMP_DIR>${path.sep + homeRealRelativeToTemp}`)
-        .join('<HOME_DIR>'), // untested
+        .join('<HOME_DIR>'),
 
     // Replace the Docusaurus version with a stub
     (val) => val.split(version).join('<CURRENT_VERSION>'),
@@ -134,7 +134,6 @@ function normalizePaths<T>(value: T): T {
 }
 
 function shouldUpdate(value: unknown) {
-  // return true if value is different from normalized value
   return typeof value === 'string' && normalizePaths(value) !== value;
 }
 

packages/docusaurus-mdx-loader/src/remark/toc/index.ts

@@ -79,7 +79,7 @@ export default function plugin(options: PluginOptions = {}): Transformer {
     visit(root, 'heading', (child: Heading, index, parent) => {
       const value = toString(child);
 
-      // depth:1 headings are titles and not included in the TOC
+      // depth: 1 headings are titles and not included in the TOC
       if (parent !== root || !value || child.depth < 2) {
         return;
       }

packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts

@@ -103,7 +103,7 @@ async function getImageAbsolutePath(
     await ensureImageFileExist(imageFilePath, filePath);
     return imageFilePath;
   } else if (path.isAbsolute(imagePath)) {
-    // absolute paths are expected to exist in the static folder
+    // Absolute paths are expected to exist in the static folder.
     const possiblePaths = staticDirs.map((dir) => path.join(dir, imagePath));
     const imageFilePath = await findAsyncSequential(
       possiblePaths,
@@ -120,7 +120,7 @@ async function getImageAbsolutePath(
     }
     return imageFilePath;
   }
-  // relative paths are resolved against the source file's folder
+  // Relative paths are resolved against the source file's folder.
   const imageFilePath = path.join(
     path.dirname(filePath),
     decodeURIComponent(imagePath),

packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts

@@ -34,7 +34,9 @@ type Context = PluginOptions & {
   filePath: string;
 };
 
-// transform the link node to a jsx link with a require() call
+/**
+ * Transforms the link node to a JSX `<a>` element with a `require()` call.
+ */
 function toAssetRequireNode(node: Link, assetPath: string, filePath: string) {
   const jsxNode = node as Literal & Partial<Link>;
   let relativeAssetPath = posixPath(
@@ -106,7 +108,7 @@ async function getAssetAbsolutePath(
 
 async function processLinkNode(node: Link, context: Context) {
   if (!node.url) {
-    // try to improve error feedback
+    // Try to improve error feedback
     // see https://github.com/facebook/docusaurus/issues/3309#issuecomment-690371675
     const title = node.title || (node.children[0] as Literal)?.value || '?';
     const line = node?.position?.start?.line || '?';

packages/docusaurus-migrate/src/index.ts

@@ -207,7 +207,7 @@ export function createConfigFile({
 >): VersionTwoConfig {
   const siteConfig = v1Config;
   const customConfigFields: {[key: string]: unknown} = {};
-  // add fields that are unknown to v2 to customConfigFields
+  // Add fields that are unknown to v2 to customConfigFields
   Object.keys(siteConfig).forEach((key) => {
     const knownFields = [
       'title',

packages/docusaurus-module-type-aliases/src/index.d.ts

@@ -152,9 +152,7 @@ declare module '@docusaurus/Link' {
       readonly href?: string;
       readonly autoAddBaseUrl?: boolean;
 
-      /**
-       * escape hatch in case broken links check is annoying for a specific link
-       */
+      /** Escape hatch in case broken links check doesn't make sense. */
       readonly 'data-noBrokenLinkCheck'?: boolean;
     };
   export default function Link(props: Props): JSX.Element;

packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts

@@ -96,8 +96,8 @@ function filterUnwantedRedirects(
   redirects: RedirectMetadata[],
   pluginContext: PluginContext,
 ): RedirectMetadata[] {
-  // we don't want to create twice the same redirect
-  // that would lead to writing twice the same html redirection file
+  // We don't want to create the same redirect twice, since that would lead to
+  // writing the same html redirection file twice.
   Object.entries(_.groupBy(redirects, (redirect) => redirect.from)).forEach(
     ([from, groupedFromRedirects]) => {
       if (groupedFromRedirects.length > 1) {

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

@@ -158,7 +158,6 @@ describe('blog plugin', () => {
       readingTime: 0.015,
       source: path.posix.join(
         '@site',
-        // pluginPath,
         path.posix.join('i18n', 'en', 'docusaurus-plugin-content-blog'),
         '2018-12-14-Happy-First-Birthday-Slash.md',
       ),
@@ -421,7 +420,7 @@ describe('blog plugin', () => {
     const blogPosts = await getBlogPosts(siteDir);
     const noDateSource = path.posix.join('@site', PluginPath, 'no date.md');
     const noDateSourceFile = path.posix.join(siteDir, PluginPath, 'no date.md');
-    // we know the file exist and we know we have git
+    // We know the file exists and we know we have git
     const result = getFileCommitDate(noDateSourceFile, {age: 'oldest'});
     const noDateSourceTime = result.date;
     const formattedDate = Intl.DateTimeFormat('en', {

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

@@ -13,7 +13,7 @@ function testValidate(options: Options) {
   return validateOptions({validate: normalizePluginOptions, options});
 }
 
-// the type of remark/rehype plugins can be either function, object or array
+// The type of remark/rehype plugins can be either function, object or array
 const markdownPluginsFunctionStub = () => {};
 const markdownPluginsObjectStub = {};
 

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -218,7 +218,7 @@ export default async function pluginContentBlog(
           routeBasePath,
           archiveBasePath,
         ]);
-        // creates a blog archive route
+        // Create a blog archive route
         const archiveProp = await createData(
           `${docuHash(archiveUrl)}.json`,
           JSON.stringify({blogPosts}, null, 2),

packages/docusaurus-plugin-content-blog/src/options.ts

@@ -111,7 +111,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
       .default(DEFAULT_OPTIONS.feedOptions.type),
     title: Joi.string().allow(''),
     description: Joi.string().allow(''),
-    // only add default value when user actually wants a feed (type is not null)
+    // Only add default value when user actually wants a feed (type is not null)
     copyright: Joi.when('type', {
       is: Joi.any().valid(null),
       then: Joi.string().optional(),

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(),