Clarify some of the comments

x-pack/plugins/security_solution/public/detection_engine/rule_management/components/rule_details/json_diff/diff_view.tsx

@@ -15,13 +15,38 @@ import {
   tokenize,
 } from 'react-diff-view';
 import 'react-diff-view/style/index.css';
-import type { RenderGutter, HunkData, TokenizeOptions, DiffProps } from 'react-diff-view';
+import type {
+  RenderGutter,
+  HunkData,
+  TokenizeOptions,
+  DiffProps,
+  HunkTokens,
+} from 'react-diff-view';
 import unidiff from 'unidiff';
 import { useEuiTheme } from '@elastic/eui';
 import { Hunks } from './hunks';
 import { markEdits, DiffMethod } from './mark_edits';
 
-const useExpand = (hunks: HunkData[], oldSource: string, newSource: string) => {
+interface UseExpandReturn {
+  expandRange: (start: number, end: number) => void;
+  hunks: HunkData[];
+}
+
+/**
+ * @param {HunkData[]} hunks - An array of ChangeData representing the changes in the block.
+ * @param {string} oldSource - The method used for performing the diff.
+ * @returns {UseExpandReturn} - "expandRange" is function that triggers expansion, "hunks" is an array of hunks with hidden section expanded.
+ *
+ * @description
+ * Sections of diff without changes are hidden by default, because they are not present in the "hunks" array.
+ * "useExpand" allows to show these hidden sections when user clicks on "Expand hidden <number> lines" button.
+ * Calling "expandRange" basically merges two adjacent hunks into one:
+ * - takes first hunk
+ * - appends all the lines between the first hunk and the second hunk
+ * - finally appends the second hunk
+ * returned "hunks" is the resulting array of hunks with hidden section expanded.
+ */
+const useExpand = (hunks: HunkData[], oldSource: string): UseExpandReturn => {
   const [hunksWithSourceExpanded, expandRange] = useSourceExpansion(hunks, oldSource);
   const hunksWithMinLinesCollapsed = useMinCollapsedLines(0, hunksWithSourceExpanded, oldSource);
 
@@ -31,7 +56,11 @@ const useExpand = (hunks: HunkData[], oldSource: string, newSource: string) => {
   };
 };
 
-const useTokens = (hunks: HunkData[], diffMethod: DiffMethod, oldSource: string) => {
+const useTokens = (
+  hunks: HunkData[],
+  diffMethod: DiffMethod,
+  oldSource: string
+): HunkTokens | undefined => {
   if (!hunks) {
     return undefined;
   }
@@ -41,16 +70,16 @@ const useTokens = (hunks: HunkData[], diffMethod: DiffMethod, oldSource: string)
     highlight: false,
     enhancers: [
       /*
-        "markEditsBy" is a slightly modified version of "markEdits" enhancer from react-diff-view
-        to enable word-level highlighting.
+        This custom "markEdits" function is a slightly modified version of "markEdits" 
+        enhancer from react-diff-view with added support for word-level highlighting.
       */
       markEdits(hunks, diffMethod),
     ],
   };
 
   try {
     /*
-      Synchroniously applies all the enhancers to the hunks and returns an array of tokens.
+      Synchroniously apply all the enhancers to the hunks and return an array of tokens.
     */
     return tokenize(hunks, options);
   } catch (ex) {
@@ -60,8 +89,7 @@ const useTokens = (hunks: HunkData[], diffMethod: DiffMethod, oldSource: string)
 
 const renderGutter: RenderGutter = ({ change }) => {
   /*
-    Custom gutter (a column where you normally see line numbers).
-    Here's I am returning "+" or "-" so the diff is more readable by colorblind people.
+    Custom gutter: rendering "+" or "-" so the diff is readable by colorblind people.
   */
   if (change.type === 'insert') {
     return <span>{'+'}</span>;
@@ -77,24 +105,9 @@ const renderGutter: RenderGutter = ({ change }) => {
 const convertToDiffFile = (oldSource: string, newSource: string) => {
   /*
     "diffLines" call below converts two strings of text into an array of Change objects.
-    Change objects look like this:
-    [
-      ...
-      {
-        "count": 2,
-        "removed": true,
-        "value": "\"from\": \"now-540s\""
-      },
-      {
-        "count": 1,
-        "added": true,
-        "value": "\"from\": \"now-9m\""
-      },
-      ...
-    ]
-
-    "formatLines" takes an array of Change objects and turns it into one big "unified Git diff" string.
-    Unified Git diff is a string with Git markers added. Looks something like this:
+
+    Then "formatLines" takes an array of Change objects and turns it into a single "unified diff" string.
+    Unified diff is a string with change markers added. Looks something like:
     `
       @@ -3,16 +3,15 @@
          "author": ["Elastic"],
@@ -192,7 +205,7 @@ export const DiffView = ({
 }: DiffViewProps) => {
   /*
     "react-diff-view" components consume diffs not as a strings, but as something they call "hunks".
-    So we first need to convert our "before" and "after" strings into these "hunks".
+    So we first need to convert our "before" and "after" strings into these "hunk" objects.
     "hunks" are objects describing changed sections of code plus a few unchanged lines above and below for context.
   */
 
@@ -203,30 +216,22 @@ export const DiffView = ({
 
   /*
     Sections of diff without changes are hidden by default, because they are not present in the "hunks" array.
-
     "useExpand" allows to show these hidden sections when user clicks on "Expand hidden <number> lines" button.
-
-    "expandRange" basically merges two hunks into one: takes first hunk, appends all the lines between it and the second hunk and finally appends the second hunk.
-
-    returned "hunks" is the resulting array of hunks with hidden section expanded.
   */
-  const { expandRange, hunks } = useExpand(diffFile.hunks, oldSource, newSource);
+  const { expandRange, hunks } = useExpand(diffFile.hunks, oldSource);
 
   /*
-    Here we go over each hunk and extract tokens from it. For example, splitting strings into words,
-    so we can later highlight changes on a word-by-word basis vs line-by-line.
+    Go over each hunk and extract tokens from it. For example, split strings into words or characters.
   */
   const tokens = useTokens(hunks, diffMethod, oldSource);
 
   return (
     <CustomStyles>
       <Diff
         /*
-        "diffType": can be 'add', 'delete', 'modify', 'rename' or 'copy'
-        passing 'add' or 'delete' would skip rendering one of the sides in split view.
-        As I understand we'll never end up with anything other than 'modify' here,
-        because we always have two strings to compare.
-      */
+          "diffType": can be either 'add', 'delete', 'modify', 'rename' or 'copy'.
+          Passing 'add' or 'delete' would skip rendering one of the sides in split view.
+        */
         diffType={diffFile.type}
         hunks={hunks}
         renderGutter={renderGutter}

x-pack/plugins/security_solution/public/detection_engine/rule_management/components/rule_details/json_diff/mark_edits.tsx

@@ -131,8 +131,8 @@ function convertToLinesOfEdits(linesOfDiffs: Diff[][], startLineNumber: number)
   return flatMap(linesOfDiffs, (diffs, i) => diffsToEdits(diffs, startLineNumber + i));
 }
 
-function diffBy(diffMethod: DiffMethod, x: string, y: string): [Diff[], Diff[]] {
-  const jsDiffChanges: Change[] = jsDiff[diffMethod](x, y);
+function diffBy(diffMethod: DiffMethod, oldSource: string, newSource: string): [Diff[], Diff[]] {
+  const jsDiffChanges: Change[] = jsDiff[diffMethod](oldSource, newSource);
   const diffs: Diff[] = diff.convertChangesToDMP(jsDiffChanges);
 
   if (diffs.length <= 1) {
@@ -142,6 +142,14 @@ function diffBy(diffMethod: DiffMethod, x: string, y: string): [Diff[], Diff[]]
   return groupDiffs(diffs);
 }
 
+const getLineNumber = (change: ChangeData | undefined) => {
+  if (!change || isNormal(change)) {
+    return undefined;
+  }
+
+  return change.lineNumber;
+};
+
 function diffChangeBlock(
   changes: ChangeData[],
   diffMethod: DiffMethod
@@ -173,13 +181,6 @@ function diffChangeBlock(
     return [[], []];
   }
 
-  const getLineNumber = (change: ChangeData | undefined) => {
-    if (!change || isNormal(change)) {
-      return undefined;
-    }
-
-    return change.lineNumber;
-  };
   const oldStartLineNumber = getLineNumber(changes.find(isDelete));
   const newStartLineNumber = getLineNumber(changes.find(isInsert));