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