From 3ea3c2c006b6d5c70495b7761d2ef84cedeb5748 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 22 Mar 2026 19:21:10 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Docs:=20Add=20missing=20JSDoc/TS?= =?UTF-8?q?Doc=20to=20components=20and=20utilities?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added `@param` and `@returns` tags to `CopyButton.tsx` and `ExerciseWidget.tsx`. - Documented `MarkdownRenderer` and its parser function. - Added JSDoc for `Sidebar` component. - Provided standard TSDoc block for `prism.ts`. - Documented `curriculumConfig.ts` constants with appropriate type tags. - Verified all documentation and tested via pre-commit linting checks. - Appended progress to `.jules/docs-progress.md`. Co-authored-by: saint2706 <45678566+saint2706@users.noreply.github.com> --- .jules/docs-progress.md | 5 +++++ src/components/CopyButton.tsx | 10 ++++++++++ src/components/ExerciseWidget.tsx | 12 ++++++++++++ src/components/MarkdownRenderer.tsx | 11 ++++++++++- src/components/Sidebar.tsx | 7 ++++--- src/utils/curriculumConfig.ts | 4 ++++ src/utils/prism.ts | 7 +++++++ 7 files changed, 52 insertions(+), 4 deletions(-) diff --git a/.jules/docs-progress.md b/.jules/docs-progress.md index a79856fd..dc91c0e9 100644 --- a/.jules/docs-progress.md +++ b/.jules/docs-progress.md @@ -35,3 +35,8 @@ - **[2026-03-20] Markdown Links & Link Checker configuration** - Updated `mlc_config.json` configuration file to ignore `keras.io` and `developers.google.com/machine-learning/crash-course` which return false positives (403 or 0 codes) from anti-bot mechanisms. - Successfully passed `markdown-link-check` script. + +- **[2026-03-22] JSDoc Improvements** + - Added missing typed JSDoc comments and `@returns` tags to `src/components/CopyButton.tsx`, `src/components/ExerciseWidget.tsx`, `src/components/MarkdownRenderer.tsx`, and `src/components/Sidebar.tsx`. + - Added missing typed JSDoc comments and `@returns` tags to `src/utils/prism.ts` and `src/utils/curriculumConfig.ts`. + - All modified components and utilities now meet documentation standards. diff --git a/src/components/CopyButton.tsx b/src/components/CopyButton.tsx index 41d8f849..6da1a41f 100644 --- a/src/components/CopyButton.tsx +++ b/src/components/CopyButton.tsx @@ -22,6 +22,16 @@ interface CopyButtonProps { ariaLabel?: string } +/** + * Renders a button that copies the provided text to the clipboard when clicked. + * + * @param {CopyButtonProps} props - The component properties. + * @param {string} props.text - The text content to be copied. + * @param {string} [props.className='code-block-copy'] - Optional custom class names. + * @param {boolean} [props.showEmoji=false] - Whether to display a clipboard emoji icon. + * @param {string} [props.ariaLabel] - Optional aria-label for accessibility. + * @returns {React.ReactElement} The rendered button component. + */ export default function CopyButton({ text, className = 'code-block-copy', diff --git a/src/components/ExerciseWidget.tsx b/src/components/ExerciseWidget.tsx index 24d24101..e8ec757a 100644 --- a/src/components/ExerciseWidget.tsx +++ b/src/components/ExerciseWidget.tsx @@ -66,6 +66,18 @@ interface ExerciseWidgetProps { solution?: string } +/** + * Renders an interactive exercise widget for practicing Python code. + * + * @param {ExerciseWidgetProps} props - The component properties. + * @param {string} props.title - Exercise title (must be unique within the day). + * @param {string} [props.goal] - Brief goal statement explaining what to achieve. + * @param {string} [props.instructions] - Detailed step-by-step instructions. + * @param {string} props.starterCode - Initial code populated in the editor. + * @param {string} [props.expectedOutput] - The exact output string the user code should produce to pass. + * @param {string} [props.solution] - Complete solution code for reference. + * @returns {React.ReactElement} The rendered exercise widget component. + */ export default function ExerciseWidget({ title, goal, diff --git a/src/components/MarkdownRenderer.tsx b/src/components/MarkdownRenderer.tsx index dcd0ba63..66993b4a 100644 --- a/src/components/MarkdownRenderer.tsx +++ b/src/components/MarkdownRenderer.tsx @@ -366,7 +366,12 @@ function extractLabeledTextFromParagraph(node: Content, label: string): string { return rest.replace(/^:\s*/, '').trim() } -/** Parse exercise and mastery sections so they can render as interactive widgets. */ +/** + * Parse exercise and mastery sections so they can render as interactive widgets. + * + * @param {string} content - The raw markdown content to be parsed. + * @returns {InteractiveBlock[]} An array of objects representing parsed blocks (text, exercises, or mastery checks). + */ function findInteractiveBlocks(content: string): InteractiveBlock[] { const tree = unified().use(remarkParse).use(remarkGfm).parse(content) as Root const topLevelNodes = tree.children @@ -692,6 +697,10 @@ interface MarkdownRendererProps { /** * Render lesson markdown with safe HTML, custom code blocks, glossary tooltips, * and interactive exercise/mastery widgets. + * + * @param {MarkdownRendererProps} props - The component properties. + * @param {string} props.content - The raw markdown content string to be rendered. + * @returns {React.ReactElement} The rendered markdown content wrapped in a responsive container. */ function MarkdownRenderer({ content }: MarkdownRendererProps) { if (!content) { diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx index 2f4d122d..bd57f621 100644 --- a/src/components/Sidebar.tsx +++ b/src/components/Sidebar.tsx @@ -35,9 +35,10 @@ interface SidebarProps { * - Mobile overlay with click-outside to close * - Phase-level progress counters * - * @param isOpen - Controls sidebar visibility on mobile. - * @param onClose - Function to close the sidebar. - * @returns A navigation sidebar with phase accordion. + * @param {SidebarProps} props - The component properties. + * @param {boolean} props.isOpen - Controls sidebar visibility on mobile. + * @param {() => void} props.onClose - Function to close the sidebar. + * @returns {React.ReactElement} A navigation sidebar with phase accordion. */ export default function Sidebar({ isOpen, onClose }: SidebarProps) { const location = useLocation() diff --git a/src/utils/curriculumConfig.ts b/src/utils/curriculumConfig.ts index f419b3df..131a6400 100644 --- a/src/utils/curriculumConfig.ts +++ b/src/utils/curriculumConfig.ts @@ -28,6 +28,8 @@ export type PhaseIcons = z.infer /** * Configuration mapping for lesson difficulty levels, providing labels and associated UI styling colors. * Validated against `difficultyConfigSchema`. + * + * @type {DifficultyConfig} */ export const difficultyConfig: DifficultyConfig = difficultyConfigSchema.parse({ beginner: { label: 'Beginner', color: '#22c55e', bg: 'rgba(34,197,94,0.12)' }, @@ -39,6 +41,8 @@ export const difficultyConfig: DifficultyConfig = difficultyConfigSchema.parse({ /** * Ordered array of icons representing the 9 curriculum phases. * Validated against `phaseIconsSchema`. + * + * @type {PhaseIcons} */ export const phaseIcons: PhaseIcons = phaseIconsSchema.parse([ '🐍', diff --git a/src/utils/prism.ts b/src/utils/prism.ts index 552ae06f..33ded105 100644 --- a/src/utils/prism.ts +++ b/src/utils/prism.ts @@ -24,4 +24,11 @@ SyntaxHighlighter.registerLanguage('markdown', markdown) SyntaxHighlighter.registerLanguage('typescript', typescript) SyntaxHighlighter.registerLanguage('javascript', javascript) +/** + * A configured instance of `react-syntax-highlighter` using PrismLight. + * This exported component has language definitions for python, bash, json, + * markdown, typescript, and javascript pre-registered to minimize bundle size. + * + * @type {React.ComponentType} + */ export default SyntaxHighlighter