From d75da61100c3839b11394aca3bb02cbd73696c50 Mon Sep 17 00:00:00 2001 From: Andrea leopardi Date: Sun, 12 Mar 2023 13:44:56 -0600 Subject: [PATCH 1/3] Show :since metadata in modules :since was showing for functions, types, and callbacks, but not for modules. --- lib/ex_doc/nodes.ex | 2 +- lib/ex_doc/retriever.ex | 17 ++++++----------- test/ex_doc/retriever/elixir_test.exs | 5 +++-- 3 files changed, 10 insertions(+), 14 deletions(-) diff --git a/lib/ex_doc/nodes.ex b/lib/ex_doc/nodes.ex index 0d7f377f3..43f0f7d85 100644 --- a/lib/ex_doc/nodes.ex +++ b/lib/ex_doc/nodes.ex @@ -22,7 +22,7 @@ defmodule ExDoc.ModuleNode do language: nil, annotations: [] - @typep annotation :: atom() + @typep annotation :: atom() | String.t() @type t :: %__MODULE__{ id: String.t(), diff --git a/lib/ex_doc/retriever.ex b/lib/ex_doc/retriever.ex index ba627ed63..d9ae9dcdd 100644 --- a/lib/ex_doc/retriever.ex +++ b/lib/ex_doc/retriever.ex @@ -140,7 +140,7 @@ defmodule ExDoc.Retriever do source_path: source_path, source_url: source_link(source, module_data.line), language: module_data.language, - annotations: List.wrap(metadata[:tags]) + annotations: List.wrap(metadata[:tags]) ++ annotations_from_metadata(metadata) } end @@ -345,16 +345,11 @@ defmodule ExDoc.Retriever do defp signature(list) when is_list(list), do: Enum.join(list, " ") defp annotations_from_metadata(metadata) do - annotations = [] - - annotations = - if since = metadata[:since] do - ["since #{since}" | annotations] - else - annotations - end - - annotations + if since = metadata[:since] do + ["since #{since}"] + else + [] + end end defp anno_line(line) when is_integer(line), do: abs(line) diff --git a/test/ex_doc/retriever/elixir_test.exs b/test/ex_doc/retriever/elixir_test.exs index 51984dca6..7d81697ec 100644 --- a/test/ex_doc/retriever/elixir_test.exs +++ b/test/ex_doc/retriever/elixir_test.exs @@ -11,6 +11,7 @@ defmodule ExDoc.Retriever.ElixirTest do defmodule Mod do @moduledoc "Mod docs." @moduledoc tags: :public + @moduledoc since: "0.15.0" @doc "function/0 docs." @spec function() :: atom() @@ -37,7 +38,7 @@ defmodule ExDoc.Retriever.ElixirTest do type: :module, typespecs: [], docs: [empty_doc_and_specs, function, macro], - annotations: [:public] + annotations: [:public, "since 0.15.0"] } = mod assert DocAST.to_string(mod.doc) == "

Mod docs.

" @@ -47,7 +48,7 @@ defmodule ExDoc.Retriever.ElixirTest do annotations: [], defaults: [], deprecated: nil, - doc_line: 5, + doc_line: 6, group: :Functions, id: "function/0", name: :function, From db445daafba667ffd46888a5111f8064d216660e Mon Sep 17 00:00:00 2001 From: Andrea leopardi Date: Mon, 13 Mar 2023 20:15:35 +0100 Subject: [PATCH 2/3] Update style --- assets/css/content/general.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/assets/css/content/general.css b/assets/css/content/general.css index b3f71923f..b588a2feb 100644 --- a/assets/css/content/general.css +++ b/assets/css/content/general.css @@ -37,6 +37,10 @@ font-weight: normal; } +.content-inner h1 .note { + font-family: var(--monoFontFamily); +} + .content-inner h2 { font-size: 1.6em; margin: 1em 0 .5em; From 0edfecf0b29704b160163a7b842f159968e7a843 Mon Sep 17 00:00:00 2001 From: Andrea leopardi Date: Tue, 14 Mar 2023 16:57:46 +0100 Subject: [PATCH 3/3] More --- README.md | 2 +- assets/css/content/general.css | 8 ------- lib/ex_doc/nodes.ex | 2 +- lib/ex_doc/retriever.ex | 25 ++++++++++---------- test/ex_doc/retriever/elixir_test.exs | 34 ++++++++++++++++++++++++--- 5 files changed, 46 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index ffd4d83dc..460c395f8 100644 --- a/README.md +++ b/README.md @@ -144,7 +144,7 @@ ExDoc supports metadata keys in your documentation. In Elixir, you can add metadata to modules and functions. -For a module, use `@moduledoc`: +For a module, use `@moduledoc`, which is equivalent to adding the annotation to everything inside the module (functions, macros, callbacks, types): ```elixir @moduledoc since: "1.10.0" diff --git a/assets/css/content/general.css b/assets/css/content/general.css index b588a2feb..42425bc5c 100644 --- a/assets/css/content/general.css +++ b/assets/css/content/general.css @@ -37,10 +37,6 @@ font-weight: normal; } -.content-inner h1 .note { - font-family: var(--monoFontFamily); -} - .content-inner h2 { font-size: 1.6em; margin: 1em 0 .5em; @@ -97,10 +93,6 @@ font-weight: normal; } -.content-inner h1 .note { - float: right; -} - .content-inner blockquote { border-left: 3px solid var(--blockquoteBorder); position: relative; diff --git a/lib/ex_doc/nodes.ex b/lib/ex_doc/nodes.ex index 43f0f7d85..0d7f377f3 100644 --- a/lib/ex_doc/nodes.ex +++ b/lib/ex_doc/nodes.ex @@ -22,7 +22,7 @@ defmodule ExDoc.ModuleNode do language: nil, annotations: [] - @typep annotation :: atom() | String.t() + @typep annotation :: atom() @type t :: %__MODULE__{ id: String.t(), diff --git a/lib/ex_doc/retriever.ex b/lib/ex_doc/retriever.ex index d9ae9dcdd..9c9ea3788 100644 --- a/lib/ex_doc/retriever.ex +++ b/lib/ex_doc/retriever.ex @@ -140,7 +140,7 @@ defmodule ExDoc.Retriever do source_path: source_path, source_url: source_link(source, module_data.line), language: module_data.language, - annotations: List.wrap(metadata[:tags]) ++ annotations_from_metadata(metadata) + annotations: List.wrap(metadata[:tags]) } end @@ -197,13 +197,13 @@ defmodule ExDoc.Retriever do groups_for_docs, annotations_for_docs ) do - {:docs_v1, _, _, content_type, _, _, _} = module_data.docs + {:docs_v1, _, _, content_type, _, module_metadata, _} = module_data.docs {{type, name, arity}, anno, signature, doc_content, metadata} = doc_element doc_line = anno_line(anno) annotations = annotations_for_docs.(metadata) ++ - annotations_from_metadata(metadata) ++ function_data.extra_annotations + annotations_from_metadata(metadata, module_metadata) ++ function_data.extra_annotations line = function_data.line || doc_line defaults = get_defaults(name, arity, Map.get(metadata, :defaults, 0)) @@ -270,7 +270,7 @@ defmodule ExDoc.Retriever do defp get_callback(callback, source, groups_for_docs, module_data, annotations_for_docs) do callback_data = module_data.language.callback_data(callback, module_data) - {:docs_v1, _, _, content_type, _, _, _} = module_data.docs + {:docs_v1, _, _, content_type, _, module_metadata, _} = module_data.docs {{kind, name, arity}, anno, _signature, doc, metadata} = callback doc_line = anno_line(anno) @@ -279,7 +279,7 @@ defmodule ExDoc.Retriever do annotations = annotations_for_docs.(metadata) ++ - callback_data.extra_annotations ++ annotations_from_metadata(metadata) + callback_data.extra_annotations ++ annotations_from_metadata(metadata, module_metadata) doc_ast = doc_ast(content_type, doc, file: source.path, line: doc_line + 1) @@ -314,10 +314,10 @@ defmodule ExDoc.Retriever do end defp get_type(type_entry, source, module_data) do - {:docs_v1, _, _, content_type, _, _, _} = module_data.docs + {:docs_v1, _, _, content_type, _, module_metadata, _} = module_data.docs {{_, name, arity}, anno, _signature, doc, metadata} = type_entry doc_line = anno_line(anno) - annotations = annotations_from_metadata(metadata) + annotations = annotations_from_metadata(metadata, module_metadata) type_data = module_data.language.type_data(type_entry, module_data) signature = signature(type_data.signature) @@ -344,11 +344,12 @@ defmodule ExDoc.Retriever do defp signature(list) when is_list(list), do: Enum.join(list, " ") - defp annotations_from_metadata(metadata) do - if since = metadata[:since] do - ["since #{since}"] - else - [] + defp annotations_from_metadata(metadata, module_metadata) do + # Give precedence to the function/callback/type metadata over the module metadata. + cond do + since = metadata[:since] -> ["since #{since}"] + since = module_metadata[:since] -> ["since #{since}"] + true -> [] end end diff --git a/test/ex_doc/retriever/elixir_test.exs b/test/ex_doc/retriever/elixir_test.exs index 7d81697ec..6c69a5636 100644 --- a/test/ex_doc/retriever/elixir_test.exs +++ b/test/ex_doc/retriever/elixir_test.exs @@ -11,7 +11,6 @@ defmodule ExDoc.Retriever.ElixirTest do defmodule Mod do @moduledoc "Mod docs." @moduledoc tags: :public - @moduledoc since: "0.15.0" @doc "function/0 docs." @spec function() :: atom() @@ -38,7 +37,7 @@ defmodule ExDoc.Retriever.ElixirTest do type: :module, typespecs: [], docs: [empty_doc_and_specs, function, macro], - annotations: [:public, "since 0.15.0"] + annotations: [:public] } = mod assert DocAST.to_string(mod.doc) == "

Mod docs.

" @@ -48,7 +47,7 @@ defmodule ExDoc.Retriever.ElixirTest do annotations: [], defaults: [], deprecated: nil, - doc_line: 6, + doc_line: 5, group: :Functions, id: "function/0", name: :function, @@ -392,5 +391,34 @@ defmodule ExDoc.Retriever.ElixirTest do assert in_the_middle_2.defaults == [] assert in_the_middle_3.defaults == [] end + + test "if @moduledoc has the :since attribute, it's applied to everything in the module", c do + elixirc(c, ~S""" + defmodule Mod do + @moduledoc since: "1.0.0" + + @type t() :: :ok + + def function(), do: :ok + + defmacro macro(), do: :ok + + @callback cb() :: :ok + end + """) + + assert [%ExDoc.ModuleNode{} = mod] = Retriever.docs_from_modules([Mod], %ExDoc.Config{}) + + assert [%ExDoc.TypeNode{id: "t:t/0", annotations: ["since 1.0.0"]}] = mod.typespecs + + assert %ExDoc.FunctionNode{annotations: ["since 1.0.0"]} = + Enum.find(mod.docs, &(&1.id == "c:cb/0")) + + assert %ExDoc.FunctionNode{annotations: ["since 1.0.0"]} = + Enum.find(mod.docs, &(&1.id == "function/0")) + + assert %ExDoc.FunctionNode{annotations: ["since 1.0.0", "macro"]} = + Enum.find(mod.docs, &(&1.id == "macro/0")) + end end end