Show documentation metadata in IEx (only since and deprecated for now) (#7886)

Author: lackac

lib/elixir/lib/io/ansi/docs.ex

@@ -7,12 +7,13 @@ defmodule IO.ANSI.Docs do
   @doc """
   The default options used by this module.
 
-  The supported values are:
+  The supported keys are:
 
     * `:enabled`           - toggles coloring on and off (true)
     * `:doc_bold`          - bold text (bright)
     * `:doc_code`          - code blocks (cyan)
     * `:doc_headings`      - h1, h2, h3, h4, h5, h6 headings (yellow)
+    * `:doc_metadata`      - documentation metadata keys (yellow)
     * `:doc_inline_code`   - inline code (cyan)
     * `:doc_table_heading` - the style for table headings
     * `:doc_title`         - top level heading (reverse, yellow)
@@ -29,6 +30,7 @@ defmodule IO.ANSI.Docs do
       doc_bold: [:bright],
       doc_code: [:cyan],
       doc_headings: [:yellow],
+      doc_metadata: [:yellow],
       doc_inline_code: [:cyan],
       doc_table_heading: [:reverse],
       doc_title: [:reverse, :yellow],
@@ -53,6 +55,39 @@ defmodule IO.ANSI.Docs do
     newline_after_block()
   end
 
+  @doc """
+  Prints documentation metadata (only `since` and `deprecated` for now).
+
+  See `default_options/0` for docs on the supported options.
+  """
+  @spec print_metadata(map, keyword) :: :ok
+  def print_metadata(metadata, options \\ []) when is_map(metadata) do
+    options = Keyword.merge(default_options(), options)
+    print_each_metadata(metadata, options) && IO.write("\n")
+  end
+
+  @metadata_filter [:deprecated, :since]
+
+  defp print_each_metadata(metadata, options) do
+    Enum.reduce(metadata, false, fn
+      {key, value}, _printed when is_binary(value) and key in @metadata_filter ->
+        label = metadata_label(key, options)
+        indent = String.duplicate(" ", length_without_escape(label, 0) + 1)
+        write_with_wrap([label | String.split(value, @spaces)], options[:width], indent, true)
+
+      _metadata, printed ->
+        printed
+    end)
+  end
+
+  defp metadata_label(key, options) do
+    if options[:enabled] do
+      "#{color(:doc_metadata, options)}#{key}:#{IO.ANSI.reset()}"
+    else
+      "#{key}:"
+    end
+  end
+
   @doc """
   Prints the documentation body.
 

lib/elixir/test/elixir/io/ansi/docs_test.exs

@@ -8,6 +8,10 @@ defmodule IO.ANSI.DocsTest do
     capture_io(fn -> IO.ANSI.Docs.print_heading(str, []) end) |> String.trim_trailing()
   end
 
+  def format_metadata(map) do
+    capture_io(fn -> IO.ANSI.Docs.print_metadata(map, []) end)
+  end
+
   def format(str) do
     capture_io(fn -> IO.ANSI.Docs.print(str, []) end) |> String.trim_trailing()
   end
@@ -19,6 +23,12 @@ defmodule IO.ANSI.DocsTest do
     assert String.contains?(result, " wibble ")
   end
 
+  test "metadata is formatted" do
+    result = format_metadata(%{since: "1.2.3", deprecated: "Use that other one", author: "Alice"})
+    assert result == "\e[33mdeprecated:\e[0m Use that other one\n\e[33msince:\e[0m 1.2.3\n\n"
+    assert format_metadata(%{author: "Alice"}) == ""
+  end
+
   test "first level heading is converted" do
     result = format("# wibble\n\ntext\n")
     assert result == "\e[33m# wibble\e[0m\n\e[0m\ntext\n\e[0m"

lib/iex/lib/iex/introspection.ex

@@ -250,8 +250,8 @@ defmodule IEx.Introspection do
     case Code.ensure_loaded(module) do
       {:module, _} ->
         case Code.fetch_docs(module) do
-          {:docs_v1, _, _, _, %{} = doc, _, _} ->
-            print_doc(inspect(module), [], doc)
+          {:docs_v1, _, _, _, %{} = doc, metadata, _} ->
+            print_doc(inspect(module), [], doc, metadata)
 
           {:docs_v1, _, _, _, _, _, _} ->
             docs_not_found(inspect(module))
@@ -376,7 +376,7 @@ defmodule IEx.Introspection do
 
       is_nil(docs) and spec != [] ->
         message = %{"en" => "Module was compiled without docs. Showing only specs."}
-        print_doc("#{inspect(mod)}.#{fun}/#{arity}", spec, message)
+        print_doc("#{inspect(mod)}.#{fun}/#{arity}", spec, message, %{})
         :ok
 
       is_nil(docs) ->
@@ -449,7 +449,7 @@ defmodule IEx.Introspection do
   defp has_content?({{_, name, _}, _, _, :none, _}), do: hd(Atom.to_charlist(name)) != ?_
   defp has_content?({_, _, _, _, _}), do: true
 
-  defp print_fun(mod, {{kind, fun, arity}, _line, signature, doc, _meta}, spec) do
+  defp print_fun(mod, {{kind, fun, arity}, _line, signature, doc, metadata}, spec) do
     if callback_module = doc == :none and callback_module(mod, fun, arity) do
       filter = &match?({_, ^fun, ^arity}, elem(&1, 0))
 
@@ -458,7 +458,7 @@ defmodule IEx.Introspection do
         _ -> nil
       end
     else
-      print_doc("#{kind_to_def(kind)} #{Enum.join(signature, " ")}", spec, doc)
+      print_doc("#{kind_to_def(kind)} #{Enum.join(signature, " ")}", spec, doc, metadata)
     end
   end
 
@@ -513,7 +513,7 @@ defmodule IEx.Introspection do
       {:ok, docs} ->
         docs
         |> add_optional_callback_docs(mod)
-        |> Enum.each(fn {definition, _} -> IO.puts(definition) end)
+        |> Enum.each(fn {definition, _, _} -> IO.puts(definition) end)
     end
 
     dont_display_result()
@@ -565,12 +565,12 @@ defmodule IEx.Introspection do
           docs
           |> Enum.filter(filter)
           |> Enum.map(fn
-            {{:macrocallback, fun, arity}, _, _, doc, _} ->
+            {{:macrocallback, fun, arity}, _, _, doc, metadata} ->
               macro = {:"MACRO-#{fun}", arity + 1}
-              {format_callback(:macrocallback, fun, macro, callbacks), doc}
+              {format_callback(:macrocallback, fun, macro, callbacks), doc, metadata}
 
-            {{kind, fun, arity}, _, _, doc, _} ->
-              {format_callback(kind, fun, {fun, arity}, callbacks), doc}
+            {{kind, fun, arity}, _, _, doc, metadata} ->
+              {format_callback(kind, fun, {fun, arity}, callbacks), doc, metadata}
           end)
 
         {:ok, docs}
@@ -588,7 +588,7 @@ defmodule IEx.Introspection do
     if optional_callbacks == [] do
       docs
     else
-      docs ++ [{format_optional_callbacks(optional_callbacks), ""}]
+      docs ++ [{format_optional_callbacks(optional_callbacks), "", %{}}]
     end
   end
 
@@ -637,8 +637,8 @@ defmodule IEx.Introspection do
       {:ok, types} ->
         printed =
           for {_, {^type, _, args}} = typespec <- types do
-            doc = {format_type(typespec), type_doc(module, type, length(args))}
-            print_typespec(doc)
+            type_doc(module, type, length(args), typespec)
+            |> print_typespec()
           end
 
         if printed == [] do
@@ -657,8 +657,8 @@ defmodule IEx.Introspection do
       {:ok, types} ->
         printed =
           for {_, {^type, _, args}} = typespec <- types, length(args) == arity do
-            doc = {format_type(typespec), type_doc(module, type, arity)}
-            print_typespec(doc)
+            type_doc(module, type, arity, typespec)
+            |> print_typespec()
           end
 
         if printed == [] do
@@ -674,12 +674,12 @@ defmodule IEx.Introspection do
     dont_display_result()
   end
 
-  defp type_doc(module, type, arity) do
+  defp type_doc(module, type, arity, typespec) do
     if docs = get_docs(module, [:type]) do
-      {_, _, _, content, _} = Enum.find(docs, &match?({:type, ^type, ^arity}, elem(&1, 0)))
-      content
+      {_, _, _, content, metadata} = Enum.find(docs, &match?({:type, ^type, ^arity}, elem(&1, 0)))
+      {format_type(typespec), content, metadata}
     else
-      :none
+      {format_type(typespec), :none, %{}}
     end
   end
 
@@ -717,27 +717,31 @@ defmodule IEx.Introspection do
     IEx.color(:doc_inline_code, left) <> " " <> right
   end
 
-  defp print_doc(heading, types, doc) do
+  defp print_doc(heading, types, doc, metadata) do
     doc = translate_doc(doc) || ""
 
     if opts = IEx.Config.ansi_docs() do
       IO.ANSI.Docs.print_heading(heading, opts)
       IO.write(types)
+      IO.ANSI.Docs.print_metadata(metadata, opts)
       IO.ANSI.Docs.print(doc, opts)
     else
       IO.puts("* #{heading}\n")
       IO.write(types)
+      IO.ANSI.Docs.print_metadata(metadata, enabled: false)
       IO.puts(doc)
     end
   end
 
-  defp print_typespec({types, doc}) do
+  defp print_typespec({types, doc, metadata}) do
     IO.puts(types)
     doc = translate_doc(doc)
 
     if opts = IEx.Config.ansi_docs() do
+      IO.ANSI.Docs.print_metadata(metadata, opts)
       doc && IO.ANSI.Docs.print(doc, opts)
     else
+      IO.ANSI.Docs.print_metadata(metadata, enabled: false)
       doc && IO.puts(doc)
     end
   end

lib/iex/test/iex/helpers_test.exs

@@ -403,6 +403,38 @@ defmodule IEx.HelpersTest do
                "No documentation for Kernel.__info__ was found\n"
     end
 
+    test "prints documentation metadata" do
+      content = """
+      defmodule Sample do
+        @moduledoc "Sample module"
+        @moduledoc deprecated: "Use OtherSample", since: "1.2.3", authors: ["Alice", "Bob"]
+        @doc "With metadata"
+        @doc since: "1.2.3", author: "Alice"
+        @deprecated "Use OtherSample.with_metadata/0"
+        def with_metadata(), do: 0
+        @doc "Without metadata"
+        def without_metadata(), do: 1
+      end
+      """
+
+      filename = "sample.ex"
+
+      with_file(filename, content, fn ->
+        assert c(filename, ".") == [Sample]
+
+        assert capture_io(fn -> h(Sample) end) ==
+                 "* Sample\n\ndeprecated: Use OtherSample\nsince: 1.2.3\n\nSample module\n"
+
+        assert capture_io(fn -> h(Sample.with_metadata()) end) ==
+                 "* def with_metadata()\n\ndeprecated: Use OtherSample.with_metadata/0\nsince: 1.2.3\n\nWith metadata\n"
+
+        assert capture_io(fn -> h(Sample.without_metadata()) end) ==
+                 "* def without_metadata()\n\nWithout metadata\n"
+      end)
+    after
+      cleanup_modules([Sample])
+    end
+
     test "considers underscored functions without docs by default" do
       content = """
       defmodule Sample do
@@ -593,6 +625,27 @@ defmodule IEx.HelpersTest do
                "@callback message(t()) :: String.t()\n\n"
     end
 
+    test "prints callback documentation metadata" do
+      filename = "callback_with_metadata.ex"
+
+      content = """
+      defmodule CallbackWithMetadata do
+        @doc "callback"
+        @doc since: "1.2.3", deprecated: "Use handle_test/1", purpose: :test
+        @callback test(:foo) :: integer
+      end
+      """
+
+      with_file(filename, content, fn ->
+        assert c(filename, ".") == [CallbackWithMetadata]
+
+        assert capture_io(fn -> b(CallbackWithMetadata.test()) end) ==
+                 "@callback test(:foo) :: integer()\n\ndeprecated: Use handle_test/1\nsince: 1.2.3\n\ncallback\n"
+      end)
+    after
+      cleanup_modules([CallbackWithMetadata])
+    end
+
     test "prints optional callback" do
       filename = "optional_callbacks.ex"
 
@@ -666,6 +719,33 @@ defmodule IEx.HelpersTest do
     after
       cleanup_modules([TypeSample])
     end
+
+    test "prints type documentation metadata" do
+      content = """
+      defmodule TypeSample do
+        @typedoc "An id with description."
+        @typedoc since: "1.2.3", deprecated: "Use t/0", purpose: :test
+        @type id_with_desc :: {number, String.t}
+      end
+      """
+
+      filename = "typesample.ex"
+
+      with_file(filename, content, fn ->
+        assert c(filename, ".") == [TypeSample]
+
+        assert capture_io(fn -> t(TypeSample.id_with_desc()) end) == """
+               @type id_with_desc() :: {number(), String.t()}
+
+               deprecated: Use t/0
+               since: 1.2.3
+
+               An id with description.
+               """
+      end)
+    after
+      cleanup_modules([TypeSample])
+    end
   end
 
   describe "v" do