Improve not-found error; tidy comments; update Javadoc

Author: codesungrape

src/main/java/com/codesungrape/hmcts/bookapi/service/BookService.java

@@ -60,13 +60,20 @@ public Book createBook(BookRequest request) {
         return savedBook;
     }
 
-    // Soft Delete
+    /**
+     * Performs a soft delete on a Book entity by marking it as deleted.
+     * This operation is idempotent - repeated calls will not trigger additional database writes.
+     *
+     * @param bookId The UUID of the book to soft delete
+     * @throws ResourceNotFoundException if no book exists with the given ID
+     */
     @Transactional // Required: This method modifies data
     public void deleteBookById(UUID bookId) {
 
-        // find the book only if it's not already soft-deleted
         Book book = bookRepository.findById(bookId)
-            .orElseThrow(() -> new ResourceNotFoundException("Book not found"));
+            .orElseThrow(() -> new ResourceNotFoundException(String.format(
+                "Book not found with id: %s", bookId
+            )));
 
         // Idempotent way to mark soft-delete and save
         if (!book.isDeleted()) {

src/test/java/com/codesungrape/hmcts/bookapi/BookServiceTest.java

@@ -325,7 +325,7 @@ void testDeleteBookById_ShouldDoNothing_WhenAlreadyDeleted() {
         testBookService.deleteBookById(testId);
 
         // Assert
-        // Verify save was NEVER called (it entered the 'false' branch of if)
+        // Verify save was NEVER called (the if condition was false, so the if block was skipped)
         verify(testBookRepository, never()).save(any(Book.class));
     }
 }