docs: debug_info documentation (#223)

Author: maennchen

documentation/how_to/use-source-annotations.md

@@ -5,6 +5,26 @@ using Erlang's `:erl_anno` module. This provides comprehensive location tracking
 for sections, options, and entities, enabling better error messages, IDE
 integration, and debugging capabilities.
 
+Source annotations are only enabled when the Elixir compile option `debug_info`
+is enabled (`Code.get_compiler_option(:debug_info)` returns true). By default,
+debug info is disabled in production and in `.exs` script files, which means
+source annotations won't be available in those contexts.
+
+> #### ExUnit Test Cases {: .warning}
+>
+> If you're defining modules inside ExUnit test cases (which use `.exs` files),
+> source annotations won't be available unless you explicitly enable
+> `debug_info` in your tests.
+>
+> ```elixir
+> setup do
+>   debug_info? = Code.get_compiler_option(:debug_info)
+>   Code.put_compiler_option(:debug_info, true)
+>   on_exit(fn -> Code.put_compiler_option(:debug_info, debug_info?) end)
+>   :ok
+> end
+> ```
+
 ## What are Source Annotations?
 
 Source annotations capture metadata about where DSL elements are defined in your

lib/spark/dsl/extension.ex

@@ -2170,7 +2170,7 @@ defmodule Spark.Dsl.Extension do
 
   @spec macro_env_anno(env :: Macro.Env.t(), do_block :: Macro.t()) :: :erl_anno.anno()
   def macro_env_anno(env, do_block) do
-    if Code.compiler_options()[:debug_info] do
+    if Code.get_compiler_option(:debug_info) do
       anno = :erl_anno.new(env.line)
       anno = :erl_anno.set_file(String.to_charlist(env.file), anno)
       maybe_set_end_location(anno, do_block)

test/dsl_test.exs

@@ -5,9 +5,9 @@ defmodule Spark.DslTest do
   import Spark.CodeHelpers
 
   setup do
-    compiler_options = Code.compiler_options()
-    Code.compiler_options(debug_info: true)
-    on_exit(fn -> Code.compiler_options(compiler_options) end)
+    debug_info? = Code.get_compiler_option(:debug_info)
+    Code.put_compiler_option(:debug_info, true)
+    on_exit(fn -> Code.put_compiler_option(:debug_info, debug_info?) end)
     :ok
   end