From 19cb24d8db4ffe9e36aa992a4ad0738fd888e398 Mon Sep 17 00:00:00 2001
From: "G.Ambatte" <sean@robertson-family.nz>
Date: Fri, 10 Jan 2025 16:48:02 +1300
Subject: [PATCH] Add explanatory comments to HeaderNav.jsx

---
 .../brewRenderer/headerNav/headerNav.jsx      | 28 +++++++++++++------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/client/homebrew/brewRenderer/headerNav/headerNav.jsx b/client/homebrew/brewRenderer/headerNav/headerNav.jsx
index 1c1032a76..68963129f 100644
--- a/client/homebrew/brewRenderer/headerNav/headerNav.jsx
+++ b/client/homebrew/brewRenderer/headerNav/headerNav.jsx
@@ -21,31 +21,39 @@ const HeaderNav = React.forwardRef(({}, pagesRef)=>{
 		if(!elements) return;
 		const navList = [];
 
+		// navList is a list of objects which have the following structure:
+		// {
+		// 		depth		: how deeply indented the item should be
+		// 		text		: the text to display in the nav link
+		// 		link		: the hyperlink to navigate to when clicked
+		// 		className	: [optional] the class to apply to the nav link for styling
+		// }
+
 		elements.forEach((el)=>{
 			if(el.className.match(/\bpage\b/)) {
-				let text = `Page ${el.id.slice(1)}`;
-				if(el.querySelector('.toc')){
+				let text = `Page ${el.id.slice(1)}`;	// The ID of a page *should* always be equal to `p` followed by the page number
+				if(el.querySelector('.toc')){			// If the page contains a table of contents, add "- Contents" to the display text
 					text += ' - Contents';
 				};
 				navList.push({
-					depth     : 0,
+					depth     : 0,						// Pages are always at the least indented level
 					text      : text,
 					link      : el.id,
 					className : 'pageLink'
 				});
 				return;
 			}
-			if(el.localName.match(/^h[1-6]/)){
+			if(el.localName.match(/^h[1-6]/)){			// Header elements H1 through H6
 				navList.push({
-					depth : el.localName[1],
-					text  : el.textContent,
+					depth : el.localName[1],			// Depth is set by the header level
+					text  : el.textContent,				// Use `textContent` because `innerText` is affected by rendering, e.g. 'content-visibility: auto'
 					link  : el.id
 				});
 				return;
 			}
 			navList.push({
-				depth : 7,
-				text  : el.textContent,
+				depth : 7,								// All unmatched elements with IDs are set to the maximum depth (7)
+				text  : el.textContent,					// Use `textContent` because `innerText` is affected by rendering, e.g. 'content-visibility: auto'
 				link  : el.id
 			});
 		});
@@ -67,14 +75,18 @@ const HeaderNav = React.forwardRef(({}, pagesRef)=>{
 const HeaderNavItem = ({ link, text, depth, className })=>{
 
 	const trimString = (text, prefixLength = 0)=>{
+		// Sanity check nav link strings
 		let output = text;
 
+		// If the string has a line break, only use the first line
 		if(text.indexOf('\n')){
 			output = text.split('\n')[0];
 		}
 
+		// Trim unecessary spaces from string
 		output = output.trim();
 
+		// Reduce excessively long strings
 		const maxLength = MAX_TEXT_LENGTH - prefixLength;
 		if(output.length > maxLength){
 			return `${output.slice(0, maxLength).trim()}...`;