Add some comments, fix some comments, stub a test class

5 files changed, 38 insertions, 10 deletions

diff --git a/SmartDeviceLink-iOS.xcodeproj/project.pbxproj b/SmartDeviceLink-iOS.xcodeproj/project.pbxproj
index 210dfbbf5..d9950cf7f 100644
--- a/SmartDeviceLink-iOS.xcodeproj/project.pbxproj
+++ b/SmartDeviceLink-iOS.xcodeproj/project.pbxproj
@@ -523,6 +523,7 @@
 		4A93896725BB361C0069F438 /* SDLMenuReplaceUtilities.m in Sources */ = {isa = PBXBuildFile; fileRef = 4A93896525BB361C0069F438 /* SDLMenuReplaceUtilities.m */; };
 		4AAC0DBA25C1FEBA00746D33 /* SDLMenuManagerPrivateConstants.h in Headers */ = {isa = PBXBuildFile; fileRef = 4AAC0DB825C1FEBA00746D33 /* SDLMenuManagerPrivateConstants.h */; };
 		4AAC0DBB25C1FEBA00746D33 /* SDLMenuManagerPrivateConstants.m in Sources */ = {isa = PBXBuildFile; fileRef = 4AAC0DB925C1FEBA00746D33 /* SDLMenuManagerPrivateConstants.m */; };
+		4AAC0DE025C468EC00746D33 /* SDLMenuReplaceUtilitiesSpec.m in Sources */ = {isa = PBXBuildFile; fileRef = 4AAC0DDF25C468EC00746D33 /* SDLMenuReplaceUtilitiesSpec.m */; };
 		4ABB24BA24F592620061BF55 /* NSMutableArray+Safe.h in Headers */ = {isa = PBXBuildFile; fileRef = 4ABB24B224F592620061BF55 /* NSMutableArray+Safe.h */; };
 		4ABB24BB24F592620061BF55 /* NSMutableArray+Safe.m in Sources */ = {isa = PBXBuildFile; fileRef = 4ABB24B324F592620061BF55 /* NSMutableArray+Safe.m */; };
 		4ABB24BC24F592620061BF55 /* NSBundle+SDLBundle.m in Sources */ = {isa = PBXBuildFile; fileRef = 4ABB24B424F592620061BF55 /* NSBundle+SDLBundle.m */; };
@@ -2329,6 +2330,7 @@
 		4A93896525BB361C0069F438 /* SDLMenuReplaceUtilities.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; name = SDLMenuReplaceUtilities.m; path = private/SDLMenuReplaceUtilities.m; sourceTree = "<group>"; };
 		4AAC0DB825C1FEBA00746D33 /* SDLMenuManagerPrivateConstants.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = SDLMenuManagerPrivateConstants.h; path = private/SDLMenuManagerPrivateConstants.h; sourceTree = "<group>"; };
 		4AAC0DB925C1FEBA00746D33 /* SDLMenuManagerPrivateConstants.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; name = SDLMenuManagerPrivateConstants.m; path = private/SDLMenuManagerPrivateConstants.m; sourceTree = "<group>"; };
+		4AAC0DDF25C468EC00746D33 /* SDLMenuReplaceUtilitiesSpec.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; name = SDLMenuReplaceUtilitiesSpec.m; path = DevAPISpecs/SDLMenuReplaceUtilitiesSpec.m; sourceTree = "<group>"; };
 		4ABB24B224F592620061BF55 /* NSMutableArray+Safe.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = "NSMutableArray+Safe.h"; path = "private/NSMutableArray+Safe.h"; sourceTree = "<group>"; };
 		4ABB24B324F592620061BF55 /* NSMutableArray+Safe.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = "NSMutableArray+Safe.m"; path = "private/NSMutableArray+Safe.m"; sourceTree = "<group>"; };
 		4ABB24B424F592620061BF55 /* NSBundle+SDLBundle.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = "NSBundle+SDLBundle.m"; path = "private/NSBundle+SDLBundle.m"; sourceTree = "<group>"; };
@@ -6577,11 +6579,12 @@
 		5DF40B24208FA7C500DD6FDA /* Menu */ = {
 			isa = PBXGroup;
 			children = (
-				5DF40B25208FA7DE00DD6FDA /* SDLMenuManagerSpec.m */,
 				5DAB5F502098994C00A020C8 /* SDLMenuCellSpec.m */,
+				5D76751522D920FD00E8D71A /* SDLMenuConfigurationSpec.m */,
+				5DF40B25208FA7DE00DD6FDA /* SDLMenuManagerSpec.m */,
+				4AAC0DDF25C468EC00746D33 /* SDLMenuReplaceUtilitiesSpec.m */,
 				752ECDB8228C42E100D945F4 /* SDLMenuRunScoreSpec.m */,
 				752ECDBA228C532600D945F4 /* SDLMenuUpdateAlgorithmSpec.m */,
-				5D76751522D920FD00E8D71A /* SDLMenuConfigurationSpec.m */,
 			);
 			name = Menu;
 			sourceTree = "<group>";
@@ -8716,6 +8719,7 @@
 				162E82F91A9BDE8B00906325 /* SDLSamplingRateSpec.m in Sources */,
 				5DBEFA541F434B9E009EE295 /* SDLStreamingMediaConfigurationSpec.m in Sources */,
 				1EB59CD2202DCA9B00343A61 /* SDLMassageModeSpec.m in Sources */,
+				4AAC0DE025C468EC00746D33 /* SDLMenuReplaceUtilitiesSpec.m in Sources */,
 				9FA0D00C22DF0B65009CF344 /* SDLCreateWindowResponseSpec.m in Sources */,
 				162E82CB1A9BDE8A00906325 /* SDLAppHMITypeSpec.m in Sources */,
 				EEB2537E2067D3E80069584E /* SDLSecondaryTransportManagerSpec.m in Sources */,
diff --git a/SmartDeviceLink/private/SDLMenuReplaceDynamicOperation.m b/SmartDeviceLink/private/SDLMenuReplaceDynamicOperation.m
index 9023f3b56..f1e6a4981 100644
--- a/SmartDeviceLink/private/SDLMenuReplaceDynamicOperation.m
+++ b/SmartDeviceLink/private/SDLMenuReplaceDynamicOperation.m
@@ -73,7 +73,7 @@ typedef void(^SDLMenuUpdateCompletionHandler)(NSError *__nullable error);
     NSArray<SDLMenuCell *> *newKeeps = [self sdl_filterKeepMenuItemsWithNewMenuItems:self.updatedMenu basedOnStatusList:addMenuStatus];
 
     // Since we are creating a new Menu but keeping old cells we must firt transfer the old cellIDs to the new menus kept cells.
-    [self transferCellIDFromOldCells:oldKeeps toKeptCells:newKeeps];
+    [self sdl_transferCellIDFromOldCells:oldKeeps toKeptCells:newKeeps];
 
     // TODO: We don't check cancellation or finish
     NSArray<SDLArtwork *> *artworksToBeUploaded = [SDLMenuReplaceUtilities findAllArtworksToBeUploadedFromCells:self.updatedMenu fileManager:self.fileManager windowCapability:self.windowCapability];
@@ -179,17 +179,17 @@ typedef void(^SDLMenuUpdateCompletionHandler)(NSError *__nullable error);
         NSArray<SDLMenuCell *> *oldKeeps = [self sdl_filterKeepMenuItemsWithOldMenuItems:oldKeptCells[startIndex].subCells basedOnStatusList:deleteMenuStatus];
         NSArray<SDLMenuCell *> *newKeeps = [self sdl_filterKeepMenuItemsWithNewMenuItems:newKeptCells[startIndex].subCells basedOnStatusList:addMenuStatus];
 
-        [self transferCellIDFromOldCells:oldKeeps toKeptCells:newKeeps];
+        [self sdl_transferCellIDFromOldCells:oldKeeps toKeptCells:newKeeps];
 
         __weak typeof(self) weakself = self;
         [self sdl_sendDeleteCurrentMenu:cellsToDelete withCompletionHandler:^(NSError * _Nullable error) {
             [weakself sdl_sendNewMenuCells:cellsToAdd oldMenu:weakself.currentMenu[startIndex].subCells withCompletionHandler:^(NSError * _Nullable error) {
-                // After the first set of submenu cells were added and deleted we must find the next set of subcells untll we loop through all the elemetns
+                // After the first set of submenu cells were added and deleted we must find the next set of subcells until we loop through all the elements
                 [weakself sdl_startSubMenuUpdatesWithOldKeptCells:oldKeptCells newKeptCells:newKeptCells atIndex:(startIndex + 1)];
             }];
         }];
     } else {
-        // After the first set of submenu cells were added and deleted we must find the next set of subcells untll we loop through all the elemetns
+        // After the first set of submenu cells were added and deleted we must find the next set of subcells until we loop through all the elements
         [self sdl_startSubMenuUpdatesWithOldKeptCells:oldKeptCells newKeptCells:newKeptCells atIndex:(startIndex + 1)];
     }
 }
@@ -239,7 +239,7 @@ typedef void(^SDLMenuUpdateCompletionHandler)(NSError *__nullable error);
     return [keepMenuCells copy];
 }
 
-- (void)transferCellIDFromOldCells:(NSArray<SDLMenuCell *> *)oldCells toKeptCells:(NSArray<SDLMenuCell *> *)newCells {
+- (void)sdl_transferCellIDFromOldCells:(NSArray<SDLMenuCell *> *)oldCells toKeptCells:(NSArray<SDLMenuCell *> *)newCells {
     if (oldCells.count == 0) { return; }
     for (NSUInteger i = 0; i < newCells.count; i++) {
         newCells[i].cellId = oldCells[i].cellId;
diff --git a/SmartDeviceLink/private/SDLMenuReplaceStaticOperation.m b/SmartDeviceLink/private/SDLMenuReplaceStaticOperation.m
index dde9ccfcf..f6d472a95 100644
--- a/SmartDeviceLink/private/SDLMenuReplaceStaticOperation.m
+++ b/SmartDeviceLink/private/SDLMenuReplaceStaticOperation.m
@@ -157,7 +157,7 @@ typedef void(^SDLMenuUpdateCompletionHandler)(NSError *__nullable error);
         }
     } completionHandler:^(BOOL success) {
         if (!success) {
-            SDLLogE(@"Failed to send main menu commands: %@", errors);
+            SDLLogE(@"Failed to send one or more main menu commands: %@", errors);
             return completionHandler([NSError sdl_menuManager_failedToUpdateWithDictionary:errors]);
         }
 
@@ -174,7 +174,7 @@ typedef void(^SDLMenuUpdateCompletionHandler)(NSError *__nullable error);
             }
         } completionHandler:^(BOOL success) {
             if (!success) {
-                SDLLogE(@"Failed to send sub menu commands: %@", errors);
+                SDLLogE(@"Failed to send one or more sub menu commands: %@", errors);
                 completionHandler([NSError sdl_menuManager_failedToUpdateWithDictionary:errors]);
                 return;
             }
diff --git a/SmartDeviceLink/private/SDLMenuReplaceUtilities.h b/SmartDeviceLink/private/SDLMenuReplaceUtilities.h
index 755398f11..f58ec3aa6 100644
--- a/SmartDeviceLink/private/SDLMenuReplaceUtilities.h
+++ b/SmartDeviceLink/private/SDLMenuReplaceUtilities.h
@@ -32,7 +32,12 @@ typedef void(^SDLCurrentMenuUpdatedBlock)(NSArray<SDLMenuCell *> *currentMenuCel
 
 #pragma mark - RPC Commands
 
+/// Finds and returns the command id for a given RPC request, assuming that request is an SDLDeleteSubMenu, SDLDeleteCommand, SDLAddSubMenu, or SDLAddCommand
+/// @param request The request
 + (UInt32)commandIdForRPCRequest:(SDLRPCRequest *)request;
+
+/// Finds and returns the position for a given RPC request, assuming that request is an SDLAddSubMenu, or SDLAddCommand
+/// @param request The request
 + (UInt16)positionForRPCRequest:(SDLRPCRequest *)request;
 
 /// Generate SDLDeleteCommand and SDLDeleteSubMenu RPCs for the given cells
@@ -56,11 +61,18 @@ typedef void(^SDLCurrentMenuUpdatedBlock)(NSArray<SDLMenuCell *> *currentMenuCel
 
 #pragma mark - Updating Menu Cells
 
-/// Find the menu cell given a command id and remove it from the list, then return the new list
+/// Find the menu cell given a command id and remove it from the list (or a cell in the list's subcell list, etc.)
 /// @param menuCellList The list to mutate and remove the item from
 /// @param commandId The id of the cell to find and remove
+/// @return YES if the cell was found and removed successfully, NO if it was not
 + (BOOL)removeMenuCellFromList:(NSMutableArray<SDLMenuCell *> *)menuCellList withCmdId:(UInt32)commandId;
 
+/// Finds a menu cell from newMenuList with the given commandId and inserts it into the main menu list (or a subcell list) at the given position
+/// @param commandId The command id for the cell to be found
+/// @param position The position to insert the cell into the appropriate list for it to be in
+/// @param newMenuList The complete requested new menu list. We will find the cell to insert from this list.
+/// @param mainMenuList The mutable main menu list. The place to insert the cell will be in this list or one of its cell's subcell list (or one of it's cell's subcell's subcell's list, etc.)
+/// @return YES if the cell was added successfully, NO if the cell was not
 + (BOOL)addMenuRequestWithCommandId:(UInt32)commandId position:(UInt16)position fromNewMenuList:(NSArray<SDLMenuCell *> *)newMenuList toMainMenuList:(NSMutableArray <SDLMenuCell *> *)mainMenuList;
 
 @end
diff --git a/SmartDeviceLinkTests/DevAPISpecs/SDLMenuReplaceUtilitiesSpec.m b/SmartDeviceLinkTests/DevAPISpecs/SDLMenuReplaceUtilitiesSpec.m
new file mode 100644
index 000000000..e51de7374
--- /dev/null
+++ b/SmartDeviceLinkTests/DevAPISpecs/SDLMenuReplaceUtilitiesSpec.m
@@ -0,0 +1,12 @@
+#import <Quick/Quick.h>
+#import <Nimble/Nimble.h>
+
+#import "SDLMenuReplaceUtilities.h"
+
+QuickSpecBegin(SDLMenuReplaceUtilitiesSpec)
+
+describe(@"a menu configuration", ^{
+
+});
+
+QuickSpecEnd