chore: remove redundant comments, keep decision justifications

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019b0c3d-971d-734e-903d-d043fab85ea1
Co-authored-by: Amp <amp@ampcode.com>

Author: 3 people

TODO.md

@@ -39,49 +39,13 @@ export {
   createJavaScriptRawEngine,
 } from 'shiki/engine/javascript';
 
-/**
- * Highlight code with shiki (core bundle)
- *
- * @param code - Code to highlight
- * @param lang - Language (bundled or custom)
- * @param theme - Theme (bundled, multi-theme, or custom)
- * @param options - react-shiki options + shiki options (highlighter required)
- * @returns Highlighted code based on outputFormat option:
- *   - 'react' (default): ReactNode
- *   - 'html': string
- *   - 'tokens': TokensResult
- *
- * @example
- * ```tsx
- * import { createHighlighterCore, createOnigurumaEngine } from 'react-shiki/core';
- *
- * const highlighter = await createHighlighterCore({
- *   themes: [import('@shikijs/themes/github-light'), import('@shikijs/themes/github-dark')],
- *   langs: [import('@shikijs/langs/typescript')],
- *   engine: createOnigurumaEngine(import('shiki/wasm'))
- * });
- *
- * // Default React output
- * const highlighted = useShikiHighlighter(code, 'typescript', 'github-dark', {
- *   highlighter
- * });
- *
- * // Token output for custom rendering
- * const tokens = useShikiHighlighter(code, 'typescript', 'github-dark', {
- *   highlighter,
- *   outputFormat: 'tokens'
- * });
- * ```
- *
- * Core bundle (minimal). For plug-and-play: `react-shiki` or `react-shiki/web`
- */
+/** Core bundle (minimal). Requires custom highlighter. For plug-and-play: `react-shiki` or `react-shiki/web` */
 export const useShikiHighlighter = <F extends OutputFormat = 'react'>(
   code: string,
   lang: Language,
   themeInput: Theme | Themes,
   options: HighlighterOptions<F> = {} as HighlighterOptions<F>
 ): OutputFormatMap[F] | null => {
-  // Validate that highlighter is provided
   const highlighter = validateCoreHighlighter(options.highlighter);
 
   return useBaseHook(
@@ -93,10 +57,6 @@ export const useShikiHighlighter = <F extends OutputFormat = 'react'>(
   );
 };
 
-/**
- * ShikiHighlighter component using a custom highlighter.
- * Requires a highlighter to be provided.
- */
 export const ShikiHighlighter = createShikiHighlighterComponent(
   useShikiHighlighter
 );

package/src/core.ts

@@ -37,37 +37,7 @@ export {
   createJavaScriptRawEngine,
 } from 'shiki/engine/javascript';
 
-/**
- * Highlight code with shiki (full bundle)
- *
- * @param code - Code to highlight
- * @param lang - Language (bundled or custom)
- * @param theme - Theme (bundled, multi-theme, or custom)
- * @param options - react-shiki options + shiki options
- * @returns Highlighted code based on outputFormat option:
- *   - 'react' (default): ReactNode
- *   - 'html': string
- *   - 'tokens': TokensResult
- *
- * @example
- * ```tsx
- * // Default React output
- * const highlighted = useShikiHighlighter(code, 'typescript', 'github-dark');
- *
- * // HTML output
- * const html = useShikiHighlighter(code, 'typescript', 'github-dark', {
- *   outputFormat: 'html'
- * });
- *
- * // Token output for custom rendering
- * const tokens = useShikiHighlighter(code, 'typescript', 'github-dark', {
- *   outputFormat: 'tokens'
- * });
- * ```
- *
- * Full bundle (~6.4MB minified, 1.2MB gzipped).
- * For smaller bundles: `react-shiki/web` or `react-shiki/core`
- */
+/** Full bundle (~6.4MB). For smaller: `react-shiki/web` or `react-shiki/core` */
 export const useShikiHighlighter = <F extends OutputFormat = 'react'>(
   code: string,
   lang: Language,
@@ -83,10 +53,6 @@ export const useShikiHighlighter = <F extends OutputFormat = 'react'>(
   );
 };
 
-/**
- * ShikiHighlighter component using the full bundle.
- * Includes all languages and themes for maximum compatibility.
- */
 export const ShikiHighlighter = createShikiHighlighterComponent(
   useShikiHighlighter
 );

package/src/index.ts

@@ -12,16 +12,9 @@ import type {
 import type { ReactNode } from 'react';
 import { forwardRef } from 'react';
 
-/**
- * Output formats the component can render.
- * 'tokens' returns raw data requiring custom rendering - use the hook directly.
- */
+// 'tokens' not included: returns raw data, use hook directly for custom rendering
 type ComponentRenderableFormat = 'react' | 'html';
 
-/**
- * Props for the ShikiHighlighter component.
- * Extends HighlighterOptions but restricts outputFormat to component-supported values.
- */
 export interface ShikiHighlighterProps
   extends Omit<HighlighterOptions, 'outputFormat'> {
   /**
@@ -113,10 +106,6 @@ export interface ShikiHighlighterProps
   as?: React.ElementType;
 }
 
-/**
- * Base ShikiHighlighter component factory.
- * Creates a component that uses the provided hook implementation.
- */
 export const createShikiHighlighterComponent = (
   useShikiHighlighterImpl: UseShikiHighlighter
 ) => {

package/src/lib/component.tsx

@@ -24,20 +24,13 @@ import { resolveLanguage, resolveTheme } from './resolvers';
 import { buildShikiOptions } from './options';
 import { transformOutput } from './output';
 
-/**
- * Factory function type for creating highlighter instances.
- * Different entry points provide different implementations.
- */
+// Each entry point (index, web, core) provides a different factory for bundle optimization
 type HighlighterFactory = (
   langsToLoad: ShikiLanguageRegistration,
   themesToLoad: Theme[],
   engine?: Awaitable<RegexEngine>
 ) => Promise<Highlighter | HighlighterCore>;
 
-/**
- * Base hook for syntax highlighting using Shiki.
- * Generic parameter narrows return type based on outputFormat option.
- */
 export const useShikiHighlighter = <F extends OutputFormat = 'react'>(
   code: string,
   lang: Language,
@@ -73,6 +66,7 @@ export const useShikiHighlighter = <F extends OutputFormat = 'react'>(
 
   const shikiOptions = useMemo(
     () => buildShikiOptions(languageId, themeResult, stableOpts),
+    // Revs ensure recompute even if useStableOptions returns same reference
     [languageId, themeResult, langRev, themeRev, optsRev]
   );
 

package/src/lib/hook.ts

@@ -1,8 +1,3 @@
-/**
- * Options builder for constructing Shiki configuration from react-shiki options.
- * Extracts option building logic from the hook for cleaner separation of concerns.
- */
-
 import type {
   CodeToHastOptions,
   CodeOptionsSingleTheme,
@@ -19,9 +14,6 @@ const DEFAULT_THEMES: Themes = {
   dark: 'github-dark',
 };
 
-/**
- * Build theme options for Shiki based on theme configuration
- */
 const buildThemeOptions = (
   themeResult: ThemeResult
 ):
@@ -40,10 +32,6 @@ const buildThemeOptions = (
   } as CodeOptionsSingleTheme<BundledTheme>;
 };
 
-/**
- * Build complete Shiki options from react-shiki options.
- * Handles theme configuration, transformers, and format-specific logic.
- */
 export const buildShikiOptions = <F extends OutputFormat>(
   languageId: string,
   themeResult: ThemeResult,

package/src/lib/options.ts

@@ -1,7 +1,3 @@
-/**
- * Output transformers for converting Shiki highlighter output to different formats.
- */
-
 import type { ReactNode } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
@@ -18,13 +14,13 @@ import type {
 
 import type { OutputFormat, OutputFormatMap } from './types';
 
-/**
- * Shiki's Highlighter methods are parameterized by BundledLanguage/BundledTheme,
- * but we accept dynamic string values. This type widens the method signatures.
- */
+// Widens Shiki's method signatures to accept dynamic string values for lang/theme
 type LooseHighlighter = (Highlighter | HighlighterCore) & {
   codeToTokens(code: string, options: CodeToTokensOptions): TokensResult;
-  codeToTokensBase(code: string, options: CodeToTokensBaseOptions): ThemedToken[][];
+  codeToTokensBase(
+    code: string,
+    options: CodeToTokensBaseOptions
+  ): ThemedToken[][];
 };
 
 type TransformContext = {
@@ -34,9 +30,6 @@ type TransformContext = {
   isMultiTheme: boolean;
 };
 
-/**
- * Transform highlighted code to React nodes via HAST
- */
 const transformToReact = ({
   highlighter,
   code,
@@ -48,24 +41,20 @@ const transformToReact = ({
     Fragment,
   });
 
-/**
- * Transform highlighted code to HTML string
- */
 const transformToHtml = ({
   highlighter,
   code,
   options,
 }: TransformContext): string => highlighter.codeToHtml(code, options);
 
-/**
- * Transform highlighted code to themed tokens with metadata.
- */
 const transformToTokens = ({
   highlighter,
   code,
   options,
   isMultiTheme,
 }: TransformContext): TokensResult => {
+  // Multi-theme: codeToTokens returns full TokensResult with all theme variants
+  // Single-theme: codeToTokensBase returns just tokens, we construct the rest
   if (isMultiTheme) {
     return highlighter.codeToTokens(code, options as CodeToTokensOptions);
   }
@@ -89,18 +78,12 @@ const transformToTokens = ({
   };
 };
 
-/**
- * Registry of output transformers keyed by format
- */
 const outputTransformers = {
   react: transformToReact,
   html: transformToHtml,
   tokens: transformToTokens,
 } as const;
 
-/**
- * Transform highlighter output to the specified format.
- */
 export const transformOutput = <F extends OutputFormat>(
   format: F,
   highlighter: Highlighter | HighlighterCore,