Update docs to indicate behavior of List.map/2, add tests

lib/igniter/code/list.ex

@@ -211,7 +211,7 @@ defmodule Igniter.Code.List do
     end
   end
 
-  @doc "Moves to the list item matching the given predicate"
+  @doc "Applies the given function to every element of the list. The passed function must return `{:ok, zipper}` or `:error` When `map` returns, the Zipper will point to the final element of the list."
   @spec map(Zipper.t(), (Zipper.t() -> {:ok, Zipper.t()})) :: {:ok, Zipper.t()} | :error
   def map(zipper, fun) do
     # go into first list item

test/igniter/code/list_test.exs

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2025 igniter contributors <https://github.com/ash-project/igniter/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Igniter.Code.ListTest do
+  alias Igniter.Code
+  alias Sourceror.Zipper
+
+  use ExUnit.Case
+  doctest Igniter.Code.List
+
+  describe "map/2" do
+    test "applies the function to every element in the list" do
+      {:ok, zipper} =
+        "[1, 2, 3, 4]"
+        |> Code.Common.parse_to_zipper!()
+        |> Code.List.map(fn %Zipper{node: {:__block__, meta, [n]}} = zipper ->
+          updated_node = {:__block__, meta, [n * 2]}
+          {:ok, %Zipper{zipper | node: updated_node}}
+        end)
+
+      assert {:ok, [2, 4, 6, 8]} ==
+               zipper |> Zipper.up() |> Code.Common.expand_literal()
+    end
+
+    test "the returned zipper points to the final element" do
+      {:ok, zipper} =
+        "[1, 2, 3, 4]"
+        |> Code.Common.parse_to_zipper!()
+        |> Code.List.map(fn %Zipper{node: {:__block__, meta, [n]}} = zipper ->
+          updated_node = {:__block__, meta, [n * 2]}
+          {:ok, %Zipper{zipper | node: updated_node}}
+        end)
+
+      assert {:ok, 8} == Code.Common.expand_literal(zipper)
+    end
+  end
+end