refactor: clean up TODO comments (#6399)

packages/docusaurus-migrate/src/frontMatter.ts

@@ -62,9 +62,7 @@ export function shouldQuotifyFrontMatter([key, value]: [
   if (String(value).match(/^("|').+("|')$/)) {
     return false;
   }
-  // TODO weird graymatter case
-  // title: !something need quotes
-  // but not title: something!
+  // title: !something needs quotes because otherwise it's a YAML tag.
   if (!String(value).trim().match(/^\w.*/)) {
     return true;
   }

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

@@ -162,10 +162,10 @@ declare module '@docusaurus/Link' {
 declare module '@docusaurus/Interpolate' {
   import type {ReactNode} from 'react';
 
-  // TODO use TS template literal feature to make values typesafe!
-  // (requires upgrading TS first)
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  export type ExtractInterpolatePlaceholders<Str extends string> = string;
+  export type ExtractInterpolatePlaceholders<Str extends string> =
+    Str extends `${string}{${infer Key}}${infer Rest}`
+      ? Key | ExtractInterpolatePlaceholders<Rest>
+      : never;
 
   export type InterpolateValues<
     Str extends string,

packages/docusaurus-theme-classic/src/index.ts

@@ -5,11 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {
-  DocusaurusContext,
-  Plugin,
-  PostCssOptions,
-} from '@docusaurus/types';
+import type {LoadContext, Plugin, PostCssOptions} from '@docusaurus/types';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import {getTranslationFiles, translateThemeConfig} from './translations';
 import path from 'path';
@@ -95,7 +91,7 @@ function getInfimaCSSFile(direction: string) {
 }
 
 export default function docusaurusThemeClassic(
-  context: DocusaurusContext, // TODO: LoadContext is missing some of properties
+  context: LoadContext,
   options: Options,
 ): Plugin<void> {
   const {

packages/docusaurus-theme-classic/src/theme/CodeBlock/index.tsx

@@ -44,9 +44,9 @@ export default function CodeBlock({
     setMounted(true);
   }, []);
 
-  // TODO: the title is provided by MDX as props automatically
-  // so we probably don't need to parse the metastring
-  // (note: title="xyz" => title prop still has the quotes)
+  // We still parse the metastring in case we want to support more syntax in the
+  // future. Note that MDX doesn't strip quotes when parsing metastring:
+  // "title=\"xyz\"" => title: "\"xyz\""
   const codeBlockTitle = parseCodeBlockTitle(metastring) || title;
   const prismTheme = usePrismTheme();
 

packages/docusaurus-theme-classic/src/theme/NavbarItem/index.tsx

@@ -16,7 +16,7 @@ import type {Types, Props} from '@theme/NavbarItem';
 
 const NavbarItemComponents: Record<
   Exclude<Types, undefined>,
-  // TODO: properly type this
+  // Not really worth typing, as we pass all props down immediately
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   () => (props: any) => JSX.Element
 > = {

packages/docusaurus/src/commands/build.ts

@@ -31,8 +31,10 @@ import {mapAsyncSequential} from '@docusaurus/utils';
 export default async function build(
   siteDir: string,
   cliOptions: Partial<BuildCLIOptions> = {},
-
-  // TODO what's the purpose of this arg ?
+  // When running build, we force terminate the process to prevent async
+  // operations from never returning. However, if run as part of docusaurus
+  // deploy, we have to let deploy finish.
+  // See https://github.com/facebook/docusaurus/pull/2496
   forceTerminate: boolean = true,
 ): Promise<string> {
   ['SIGINT', 'SIGTERM'].forEach((sig) => {

packages/docusaurus/src/server/__tests__/configValidation.test.ts

@@ -147,7 +147,7 @@ describe('normalizeConfig', () => {
       'should accept [function, object] for plugin',
       [[function (_context, _options) {}, {it: 'should work'}]],
     ],
-  ])(`subdue= for the input of: path=`, (_message, plugins) => {
+  ])(`%s for the input of: %p`, (_message, plugins) => {
     expect(() => {
       normalizeConfig({
         plugins,

packages/docusaurus/src/server/configValidation.ts

@@ -65,9 +65,7 @@ const PluginSchema = Joi.alternatives()
       .length(2),
     Joi.bool().equal(false), // In case of conditional adding of plugins.
   )
-  // TODO isn't there a simpler way to customize the default Joi error message???
-  // Not sure why Joi makes it complicated to add a custom error message...
-  // See https://stackoverflow.com/a/54657686/82609
+  // @ts-expect-error: bad lib def, doesn't recognize an array of reports
   .error((errors) => {
     errors.forEach((error) => {
       error.message = ` => Bad Docusaurus plugin value as path [${error.path}].
@@ -83,7 +81,7 @@ Example valid plugin config:
 };
 `;
     });
-    return errors as any;
+    return errors;
   });
 
 const ThemeSchema = Joi.alternatives().try(

packages/docusaurus/src/webpack/utils.ts

@@ -230,7 +230,7 @@ export function applyConfigurePostCss(
     options: {postcssOptions: PostCssOptions};
   };
 
-  // TODO not ideal heuristic but good enough for our usecase?
+  // not ideal heuristic but good enough for our usecase?
   function isPostCssLoader(loader: unknown): loader is LocalPostCSSLoader {
     return !!(loader as LocalPostCSSLoader)?.options?.postcssOptions;
   }

website/docs/guides/markdown-features/markdown-features-code-blocks.mdx

@@ -38,8 +38,6 @@ Code blocks are text blocks wrapped around by strings of 3 backticks. You may ch
     console.log('Every repo must come with a mascot.');
     ```
 
-<!-- TODO: We need to allow users to pick syntax highlighting themes (maybe other than swizzling) -->
-
 Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer).
 
 <BrowserWindow>
@@ -67,6 +65,8 @@ module.exports = {
 };
 ```
 
+Because a Prism theme is just a JS object, you can also write your own theme if you are not satisfied with the default. Docusaurus enhances the `github` and `vsDark` themes to provide richer highlight, and you can check our implementations for the [light](https://github.com/facebook/docusaurus/blob/main/website/src/utils/prismLight.mjs) and [dark](https://github.com/facebook/docusaurus/blob/main/website/src/utils/prismDark.mjs) code block themes.
+
 ### Supported Languages {#supported-languages}
 
 By default, Docusaurus comes with a subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).