feat: add :doc option to field macro

Co-authored-by: Balázs Jávorszky <javorszky.balazs@estyle.hu>
Co-authored-by: Jean-Philippe Cugnet <jean-philippe@cugnet.eu>

Author: javobalazs

CHANGELOG.md

@@ -13,6 +13,11 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+* Add a `:doc` option to `field/3` to add field-specific descriptions in the
+    `@typedoc` (by [@javobalazs](https://github.com/javobalazs)).
+
 ### Fixed
 
 * Ensure the second argument to `field/2` is a type ([#45]).

README.md

@@ -203,6 +203,30 @@ typedstruct do
 end
 ```
 
+You can also document individual fields:
+
+```elixir
+typedstruct do
+  @typedoc "A typed struct"
+
+  field :a_string, String.t(), doc: "just a series of letters"
+  field :an_int, integer(), doc: "some explanation"
+end
+```
+
+This generate the following `@typedoc`:
+
+```elixir
+@typedoc """
+A typed struct
+
+## Fields
+
+- `a_string` - just a series of letters
+- `an_int` - some digits
+"""
+```
+
 You can also document submodules this way:
 
 ```elixir

lib/typed_struct.ex

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2018-2022, 2025 Jean-Philippe Cugnet <jean-philippe@cugnet.eu>
 # SPDX-FileCopyrightText: 2018 Marcin Górnik <marcin.gornik@gmail.com>
 # SPDX-FileCopyrightText: 2022 Jonathan Chukinas <chukinas@gmail.com>
+# SPDX-FileCopyrightText: 2022 Balázs Jávorszky <javorszky.balazs@estyle.hu>
 #
 # SPDX-License-Identifier: MIT
 
@@ -16,6 +17,7 @@ defmodule TypedStruct do
     :ts_plugin_fields,
     :ts_fields,
     :ts_types,
+    :ts_docs,
     :ts_enforce_keys
   ]
 
@@ -116,10 +118,46 @@ defmodule TypedStruct do
       @enforce_keys @ts_enforce_keys
       defstruct @ts_fields
 
+      TypedStruct.__typedoc__(@ts_docs)
       TypedStruct.__type__(@ts_types, unquote(opts))
     end
   end
 
+  @doc false
+  defmacro __typedoc__(docs) do
+    quote bind_quoted: [docs: docs] do
+      field_docs =
+        docs
+        |> Enum.reverse()
+        |> Enum.filter(fn {_, doc} -> !is_nil(doc) end)
+        |> Enum.map(fn {name, doc} -> "- `#{name}` - #{doc}" end)
+
+      if field_docs != [] do
+        # If there are field docs, we complete the `@typedoc` with field
+        # documentation. However, if there is no `@typedoc` already, let’s emit
+        # a warning instead.
+        if Module.has_attribute?(__MODULE__, :typedoc) do
+          @typedoc """
+          #{@typedoc}
+
+          ## Fields
+
+          #{Enum.join(field_docs, "\n")}
+          """
+        else
+          IO.warn(
+            """
+            adding field documentation has no effect without a @typedoc
+
+            hint: add a @typedoc on your `typedstruct` definition
+            """,
+            Macro.Env.stacktrace(__ENV__)
+          )
+        end
+      end
+    end
+  end
+
   @doc false
   defmacro __type__(types, opts) do
     if Keyword.get(opts, :opaque, false) do
@@ -174,6 +212,7 @@ defmodule TypedStruct do
     * `default` - sets the default value for the field
     * `enforce` - if set to true, enforces the field and makes its type
       non-nullable
+    * `doc` - description for the field to be added to the `@typedoc`
   """
   defmacro field(name, type, opts \\ []) do
     quote bind_quoted: [name: name, type: Macro.escape(type), opts: opts] do
@@ -208,6 +247,7 @@ defmodule TypedStruct do
     Module.put_attribute(mod, :ts_fields, {name, opts[:default]})
     Module.put_attribute(mod, :ts_plugin_fields, {name, type, opts, env})
     Module.put_attribute(mod, :ts_types, {name, type_for(type, nullable?)})
+    Module.put_attribute(mod, :ts_docs, {name, opts[:doc]})
     if enforce?, do: Module.put_attribute(mod, :ts_enforce_keys, name)
   end
 

test/data/test_struct/no_typedoc.ex

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2025 Jean-Philippe Cugnet <jean-philippe@cugnet.eu>
+# SPDX-License-Identifier: MIT
+
+# NOTE: This file emits a warning when compiled, on purpose. To avoid printing
+# this warning, it is compiled from a test with captured I/O.
+#
+# See test "does not create a `@typedoc` if there is none" for more information.
+defmodule TypedStruct.TestStruct.NoTypedoc do
+  @moduledoc """
+  A typed struct with documented fields but no `@typedoc`.
+  """
+  use TypedStruct
+
+  typedstruct do
+    field :a_string, String.t(), doc: "just a series of letters"
+    field :an_int, integer(), doc: "some digits"
+  end
+end

test/support/test_struct.ex

@@ -93,6 +93,31 @@ defmodule TypedStruct.TestStruct do
     end
   end
 
+  defmodule SimpleTypedoc do
+    @moduledoc """
+    A typed struct with a `@typedoc`.
+    """
+    use TypedStruct
+
+    @typedoc "A typed struct"
+    typedstruct do
+      field :field, term()
+    end
+  end
+
+  defmodule DetailedTypedoc do
+    @moduledoc """
+    A typed struct with a `@typedoc`.
+    """
+    use TypedStruct
+
+    @typedoc "A typed struct"
+    typedstruct do
+      field :a_string, String.t(), doc: "just a series of letters"
+      field :an_int, integer(), doc: "some digits"
+    end
+  end
+
   defmodule Alias do
     @moduledoc """
     Structs for testing the use of aliases in types.

test/typed_struct_test.exs

@@ -87,6 +87,61 @@ defmodule TypedStructTest do
              }
   end
 
+  test "keeps the `@typedoc` if it exists" do
+    assert extract_t_typedoc(TestStruct.SimpleTypedoc) == %{
+             "en" => "A typed struct"
+           }
+  end
+
+  test "adds field descriptions to the `@typedoc` if it exists" do
+    assert extract_t_typedoc(TestStruct.DetailedTypedoc) == %{
+             "en" => """
+             A typed struct
+
+             ## Fields
+
+             - `a_string` - just a series of letters
+             - `an_int` - some digits
+             """
+           }
+  end
+
+  test "does not create a `@typedoc` if there is none" do
+    module = TestStruct.NoTypedoc
+
+    # HACK: To check the absence of @typedoc with `Code.fetch_docs/1`, we need
+    # that the module is compiled to a beam file on disk. We could put the
+    # struct in `test/support/test_struct.ex` along with other test structs,
+    # however this would emit a warning at compile time, which we want to avoid.
+    # Let’s then compile the file here while capturing the I/O to suppress the
+    # warning.
+    #
+    # NOTE: The emission of the warning is tested in a following test.
+    capture_io(:stderr, fn ->
+      File.rm("_build/test/lib/typed_struct/ebin/#{module}.beam")
+      Code.put_compiler_option(:docs, true)
+      [{_, bin}] = Code.compile_file("test/data/test_struct/no_typedoc.ex")
+      File.write!("_build/test/lib/typed_struct/ebin/#{module}.beam", bin)
+    end)
+
+    assert extract_t_typedoc(module) == :none
+  end
+
+  test "prints a warning if `:doc` is set but there is no `@typedoc`" do
+    assert capture_io(
+             :stderr,
+             fn ->
+               defmodule FieldDocWithoutTypeDoc do
+                 use TypedStruct
+
+                 typedstruct do
+                   field :field, term(), doc: "Just a field"
+                 end
+               end
+             end
+           ) =~ "adding field documentation has no effect without a @typedoc"
+  end
+
   ############################################################################
   ##                                Problems                                ##
   ############################################################################
@@ -196,4 +251,17 @@ defmodule TypedStructTest do
 
   defp standardise(list, struct) when is_list(list),
     do: Enum.map(list, &standardise(&1, struct))
+
+  # Extracts the `@typedoc` for type `t()` in `module`.
+  defp extract_t_typedoc(module) do
+    {:docs_v1, _, :elixir, _, _, _,
+     [
+       _,
+       _,
+       {{:type, :t, _}, _, _, typedoc, _}
+     ]} =
+      Code.fetch_docs(module)
+
+    typedoc
+  end
 end