refactor: capitalize comments (#7188)

* refactor: capitalize comments

* revert...

packages/docusaurus-theme-common/src/components/Collapsible/index.tsx

@@ -224,6 +224,8 @@ function CollapsibleBase({
 
 function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) {
   const [mounted, setMounted] = useState(!collapsed);
+  // Updated in effect so that first expansion transition can work
+  const [lazyCollapsed, setLazyCollapsed] = useState(collapsed);
 
   useLayoutEffect(() => {
     if (!collapsed) {
@@ -231,8 +233,6 @@ function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) {
     }
   }, [collapsed]);
 
-  // lazyCollapsed updated in effect so that first expansion transition can work
-  const [lazyCollapsed, setLazyCollapsed] = useState(collapsed);
   useLayoutEffect(() => {
     if (mounted) {
       setLazyCollapsed(collapsed);

packages/docusaurus-theme-common/src/components/Details/index.tsx

@@ -87,7 +87,8 @@ export function Details({
           setOpen(true);
         } else {
           setCollapsed(true);
-          // setOpen(false); // Don't do this, it breaks close animation!
+          // Don't do this, it breaks close animation!
+          // setOpen(false);
         }
       }}>
       {summary}

packages/docusaurus-theme-common/src/contexts/announcementBar.tsx

@@ -72,7 +72,7 @@ function useContextValue(): ContextValue {
 
     let viewedId = IdStorage.get();
 
-    // retrocompatibility due to spelling mistake of default id
+    // Retrocompatibility due to spelling mistake of default id
     // see https://github.com/facebook/docusaurus/issues/3338
     // cSpell:ignore annoucement
     if (viewedId === 'annoucement-bar') {

packages/docusaurus-theme-common/src/contexts/navbarMobileSidebar.tsx

@@ -58,9 +58,9 @@ function useContextValue(): ContextValue {
   useHistoryPopHandler(() => {
     if (shown) {
       setShown(false);
-      // Should we prevent the navigation here?
+      // Prevent pop navigation; seems desirable enough
       // See https://github.com/facebook/docusaurus/pull/5462#issuecomment-911699846
-      return false; // prevent pop navigation
+      return false;
     }
     return undefined;
   });

packages/docusaurus-theme-common/src/hooks/useTOCHighlight.ts

@@ -81,8 +81,8 @@ function getActiveAnchor(
     // https://github.com/facebook/docusaurus/issues/5318
     return anchors[anchors.indexOf(nextVisibleAnchor) - 1] ?? null;
   }
-  // no anchor under viewport top? (ie we are at the bottom of the page)
-  // => highlight the last anchor found
+  // No anchor under viewport top (i.e. we are at the bottom of the page),
+  // highlight the last anchor found
   return anchors[anchors.length - 1] ?? null;
 }
 
@@ -140,7 +140,7 @@ export function useTOCHighlight(config: TOCHighlightConfig | undefined): void {
 
   useEffect(() => {
     if (!config) {
-      // no-op, highlighting is disabled
+      // No-op, highlighting is disabled
       return () => {};
     }
 

packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts

@@ -30,14 +30,14 @@ const magicCommentDirectives = [
 ];
 
 function getCommentPattern(languages: CommentType[]) {
-  // to be more reliable, the opening and closing comment must match
+  // To be more reliable, the opening and closing comment must match
   const commentPattern = languages
     .map((lang) => {
       const {start, end} = commentPatterns[lang];
       return `(?:${start}\\s*(${magicCommentDirectives.join('|')})\\s*${end})`;
     })
     .join('|');
-  // white space is allowed, but otherwise it should be on it's own line
+  // White space is allowed, but otherwise it should be on it's own line
   return new RegExp(`^\\s*(?:${commentPattern})\\s*$`);
 }
 
@@ -70,7 +70,7 @@ function getAllMagicCommentDirectiveStyles(lang: string) {
       return getCommentPattern(['html', 'jsx', 'bash']);
 
     default:
-      // all comment types
+      // All comment types
       return getCommentPattern(Object.keys(commentPatterns) as CommentType[]);
   }
 }
@@ -139,16 +139,15 @@ export function parseLines(
     return {highlightLines: [], code};
   }
   const directiveRegex = getAllMagicCommentDirectiveStyles(language);
-  // go through line by line
+  // Go through line by line
   const lines = code.split('\n');
   let highlightBlockStart: number;
   let highlightRange = '';
-  // loop through lines
   for (let lineNumber = 0; lineNumber < lines.length; ) {
     const line = lines[lineNumber]!;
     const match = line.match(directiveRegex);
     if (!match) {
-      // lines without directives are unchanged
+      // Lines without directives are unchanged
       lineNumber += 1;
       continue;
     }

packages/docusaurus-theme-common/src/utils/docsUtils.tsx

@@ -92,13 +92,8 @@ export function findFirstCategoryLink(
       if (categoryLink) {
         return categoryLink;
       }
-    } else if (subItem.type === 'html') {
-      // skip
-    } else {
-      throw new Error(
-        `Unexpected category item type for ${JSON.stringify(subItem)}`,
-      );
     }
+    // Could be "html" items
   }
   return undefined;
 }
@@ -271,7 +266,7 @@ export function useLayoutDoc(
       const isDraft = versions
         .flatMap((version) => version.draftIds)
         .includes(docId);
-      // drafts should be silently filtered instead of throwing
+      // Drafts should be silently filtered instead of throwing
       if (isDraft) {
         return null;
       }

packages/docusaurus-theme-common/src/utils/tocUtils.ts

@@ -30,11 +30,11 @@ function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
   const prevIndexForLevel = Array(7).fill(-1);
 
   headings.forEach((curr, currIndex) => {
-    // take the last seen index for each ancestor level. the highest
-    // index will be the direct ancestor of the current heading.
+    // Take the last seen index for each ancestor level. the highest index will
+    // be the direct ancestor of the current heading.
     const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
     curr.parentIndex = Math.max(...ancestorLevelIndexes);
-    // mark that curr.level was last seen at the current index
+    // Mark that curr.level was last seen at the current index.
     prevIndexForLevel[curr.level] = currIndex;
   });