diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex index 95b44d58a..1387c1339 100644 --- a/lib/ex_doc/cli.ex +++ b/lib/ex_doc/cli.ex @@ -194,7 +194,7 @@ defmodule ExDoc.CLI do [ extras: Path.wildcard("lib/elixir/pages/*.md"), - groups_for_functions: [ + groups_for_docs: [ Guards: & &1[:guard] == true ], skip_undefined_reference_warnings_on: ["compatibility-and-deprecations"], diff --git a/lib/ex_doc/config.ex b/lib/ex_doc/config.ex index 6ebee8755..c32697b51 100644 --- a/lib/ex_doc/config.ex +++ b/lib/ex_doc/config.ex @@ -24,7 +24,7 @@ defmodule ExDoc.Config do formatter: "html", formatters: [], groups_for_extras: [], - groups_for_functions: [], + groups_for_docs: [], groups_for_modules: [], homepage_url: nil, javascript_config_path: "docs_config.js", @@ -62,7 +62,7 @@ defmodule ExDoc.Config do formatter: nil | String.t(), formatters: [String.t()], groups_for_extras: keyword(), - groups_for_functions: keyword((keyword() -> boolean)), + groups_for_docs: keyword((keyword() -> boolean)), groups_for_modules: keyword(), homepage_url: nil | String.t(), javascript_config_path: nil | String.t(), @@ -91,6 +91,14 @@ defmodule ExDoc.Config do {proglang, options} = Keyword.pop(options, :proglang, :elixir) {filter_modules, options} = Keyword.pop(options, :filter_modules, &filter_modules/2) + options = + if groups_for_functions = options[:groups_for_functions] do + # TODO: Deprecate me + Keyword.put_new(options, :groups_for_docs, groups_for_functions) + else + options + end + {source_url_pattern, options} = Keyword.pop_lazy(options, :source_url_pattern, fn -> guess_url(options[:source_url], options[:source_ref] || @default_source_ref) diff --git a/lib/ex_doc/retriever.ex b/lib/ex_doc/retriever.ex index 0f48657aa..ba627ed63 100644 --- a/lib/ex_doc/retriever.ex +++ b/lib/ex_doc/retriever.ex @@ -104,18 +104,18 @@ defmodule ExDoc.Retriever do {doc_line, moduledoc, metadata} = get_module_docs(module_data, source_path) # TODO: The default function groups must be returned by the language - groups_for_functions = - config.groups_for_functions ++ + groups_for_docs = + config.groups_for_docs ++ [Callbacks: &(&1[:__doc__] == :callback), Functions: fn _ -> true end] annotations_for_docs = config.annotations_for_docs - docs_groups = Enum.map(groups_for_functions, &elem(&1, 0)) - function_docs = get_docs(module_data, source, groups_for_functions, annotations_for_docs) + docs_groups = Enum.map(groups_for_docs, &elem(&1, 0)) + function_docs = get_docs(module_data, source, groups_for_docs, annotations_for_docs) docs = function_docs ++ - get_callbacks(module_data, source, groups_for_functions, annotations_for_docs) + get_callbacks(module_data, source, groups_for_docs, annotations_for_docs) types = get_types(module_data, source) @@ -163,7 +163,7 @@ defmodule ExDoc.Retriever do ## Function helpers - defp get_docs(module_data, source, groups_for_functions, annotations_for_docs) do + defp get_docs(module_data, source, groups_for_docs, annotations_for_docs) do {:docs_v1, _, _, _, _, _, doc_elements} = module_data.docs nodes = @@ -179,7 +179,7 @@ defmodule ExDoc.Retriever do function_data, source, module_data, - groups_for_functions, + groups_for_docs, annotations_for_docs ) ] @@ -194,7 +194,7 @@ defmodule ExDoc.Retriever do function_data, source, module_data, - groups_for_functions, + groups_for_docs, annotations_for_docs ) do {:docs_v1, _, _, content_type, _, _, _} = module_data.docs @@ -212,7 +212,7 @@ defmodule ExDoc.Retriever do (doc_content && doc_ast(content_type, doc_content, file: source.path, line: doc_line + 1)) || function_data.doc_fallback.() - group = GroupMatcher.match_function(groups_for_functions, metadata) + group = GroupMatcher.match_function(groups_for_docs, metadata) %ExDoc.FunctionNode{ id: "#{name}/#{arity}", @@ -255,19 +255,19 @@ defmodule ExDoc.Retriever do defp get_callbacks( %{type: :behaviour} = module_data, source, - groups_for_functions, + groups_for_docs, annotations_for_docs ) do {:docs_v1, _, _, _, _, _, docs} = module_data.docs for {{kind, _, _}, _, _, _, _} = doc <- docs, kind in module_data.callback_types do - get_callback(doc, source, groups_for_functions, module_data, annotations_for_docs) + get_callback(doc, source, groups_for_docs, module_data, annotations_for_docs) end end defp get_callbacks(_, _, _, _), do: [] - defp get_callback(callback, source, groups_for_functions, module_data, annotations_for_docs) 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 @@ -284,7 +284,7 @@ defmodule ExDoc.Retriever do doc_ast = doc_ast(content_type, doc, file: source.path, line: doc_line + 1) metadata = Map.put(metadata, :__doc__, :callback) - group = GroupMatcher.match_function(groups_for_functions, metadata) + group = GroupMatcher.match_function(groups_for_docs, metadata) %ExDoc.FunctionNode{ id: "c:#{name}/#{arity}", diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index 58968719b..eae7551bf 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -112,7 +112,7 @@ defmodule Mix.Tasks.Docs do * `:formatters` - Formatter to use; default: ["html", "epub"], options: "html", "epub". - * `:groups_for_extras`, `:groups_for_modules`, `:groups_for_functions` - See the "Groups" section + * `:groups_for_extras`, `:groups_for_modules`, `:groups_for_docs` - See the "Groups" section * `:ignore_apps` - Apps to be ignored when generating documentation in an umbrella project. Receives a list of atoms. Example: `[:first_app, :second_app]`. @@ -218,7 +218,7 @@ defmodule Mix.Tasks.Docs do ### Grouping functions and callbacks Functions and callbacks inside a module can also be organized in groups. - This is done via the `:groups_for_functions` configuration which is a + This is done via the `:groups_for_docs` configuration which is a keyword list of group titles and filtering functions that receive the documentation metadata of functions as argument. @@ -240,7 +240,7 @@ defmodule Mix.Tasks.Docs do And then in the configuration you can group these with: - groups_for_functions: [ + groups_for_docs: [ Authentication: & &1[:section] == :auth, Resource: & &1[:subject] == :object, Admin: & &1[:permission] in [:grant, :write] diff --git a/test/ex_doc/formatter/epub/templates_test.exs b/test/ex_doc/formatter/epub/templates_test.exs index 13ae585b9..1b456ee89 100644 --- a/test/ex_doc/formatter/epub/templates_test.exs +++ b/test/ex_doc/formatter/epub/templates_test.exs @@ -73,7 +73,7 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do test "outputs function groups" do content = get_module_page([CompiledWithDocs], - groups_for_functions: [ + groups_for_docs: [ "Example functions": &(&1[:purpose] == :example), Legacy: &is_binary(&1[:deprecated]) ] diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs index efb52b773..9f57bb231 100644 --- a/test/ex_doc/formatter/html/templates_test.exs +++ b/test/ex_doc/formatter/html/templates_test.exs @@ -280,7 +280,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do ExDoc.Retriever.docs_from_modules( [CompiledWithDocs, CompiledWithDocs.Nested], doc_config(context, - groups_for_functions: [ + groups_for_docs: [ "Example functions": &(&1[:purpose] == :example), Legacy: &is_binary(&1[:deprecated]) ] @@ -406,7 +406,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do test "outputs function groups", context do content = get_module_page([CompiledWithDocs], context, - groups_for_functions: [ + groups_for_docs: [ "Example functions": &(&1[:purpose] == :example), Legacy: &is_binary(&1[:deprecated]) ] diff --git a/test/ex_doc/retriever_test.exs b/test/ex_doc/retriever_test.exs index 0c46b0c2e..802022bba 100644 --- a/test/ex_doc/retriever_test.exs +++ b/test/ex_doc/retriever_test.exs @@ -77,7 +77,7 @@ defmodule ExDoc.RetrieverTest do """) config = %ExDoc.Config{ - groups_for_functions: [ + groups_for_docs: [ "Group 1": &(&1.group == 1), "Group 2": &(&1.group == 2) ]