From 17daa011b9b9f89179a10e2d71dbfce6be676e3b Mon Sep 17 00:00:00 2001
From: rktjmp <rktjmp@users.noreply.github.com>
Date: Sat, 21 Oct 2023 20:34:09 +1100
Subject: [PATCH] Group PageBuilder component docs under Components group
 (#428)

* Add @doc type: :component to PageBuilder components

* Add groups_for_function doc option to mix.exs

* Remove parenthesis from some page builder component slot definitions
---
 lib/phoenix/live_dashboard/page_builder.ex | 22 +++++++++++++++-------
 mix.exs                                    |  5 ++++-
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/lib/phoenix/live_dashboard/page_builder.ex b/lib/phoenix/live_dashboard/page_builder.ex
index b4a74b94..fcf84b57 100644
--- a/lib/phoenix/live_dashboard/page_builder.ex
+++ b/lib/phoenix/live_dashboard/page_builder.ex
@@ -222,6 +222,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
 
   You can see it in use the applications, processes, sockets pages and many others.
   """
+  @doc type: :component
   attr :id, :any,
     required: true,
     doc: "Because is a stateful `Phoenix.LiveComponent` an unique id is needed."
@@ -300,6 +301,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
 
   You can see it in use the Metrics and Ecto info pages.
   """
+  @doc type: :component
   attr :id, :any,
     required: true,
     doc: "Because is a stateful `Phoenix.LiveComponent` an unique id is needed."
@@ -342,6 +344,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
   @doc """
   Hint pop-up text component
   """
+  @doc type: :component
   attr :text, :string, required: true, doc: "Text to show in the hint"
 
   @spec hint(assigns :: Socket.assigns()) :: Phoenix.LiveView.Rendered.t()
@@ -362,6 +365,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
   @doc """
   Card title component.
   """
+  @doc type: :component
   attr :title, :string, default: nil, doc: "The title above the card."
   attr :hint, :string, default: nil, doc: "A textual hint to show close to the title."
 
@@ -380,8 +384,8 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
 
   You can see it in use the Home and OS Data pages.
   """
-
-  slot(:inner_block, required: true, doc: "The value that the card will show.")
+  @doc type: :component
+  slot :inner_block, required: true, doc: "The value that the card will show."
   attr :title, :string, default: nil, doc: "The title above the card."
   attr :hint, :string, default: nil, doc: "A textual hint to show close to the title."
   attr :inner_title, :string, default: nil, doc: "The title inside the card."
@@ -409,7 +413,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
 
   You can see it in use the Home page in the Environment section.
   """
-
+  @doc type: :component
   attr :fields, :list,
     required: true,
     doc: "A list of key-value elements that will be shown inside the card."
@@ -448,12 +452,12 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
 
   You can see it in use the Home page and OS Data pages.
   """
-  slot(:col,
+  @doc type: :component
+  slot :col,
     required: true,
     doc:
       "A list of components. It can receive up to 3 components." <>
         " Each element will be one column."
-  )
 
   @spec row(assigns :: Socket.assigns()) :: Phoenix.LiveView.Rendered.t()
   def row(assigns) do
@@ -485,6 +489,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
 
   You can see it in use the Home page and OS Data pages.
   """
+  @doc type: :component
   attr :title, :string, default: nil, doc: "The title above the card."
   attr :hint, :string, default: nil, doc: "A textual hint to show close to the title."
   attr :dom_id, :string, required: true, doc: "A unique identifier for all usages in this card."
@@ -542,7 +547,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
   attr :dom_id, :string, required: true
   attr :percent, :float, required: true
   attr :csp_nonces, :any, required: true
-  slot(:inner_block, required: true)
+  slot :inner_block, required: true
 
   defp title_bar_component(assigns) do
     ~H"""
@@ -575,6 +580,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
 
   You can see it in use the Home page and OS Data pages.
   """
+  @doc type: :component
   attr :usages, :list,
     required: true,
     doc: """
@@ -700,6 +706,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
       ...>    ]
       ...> ]
   """
+  @doc type: :component
   attr :id, :any,
     required: true,
     doc: "Because is a stateful `Phoenix.LiveComponent` an unique id is needed."
@@ -764,6 +771,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
 
   You can see it in use in the modal in Ports or Processes page.
   """
+  @doc type: :component
   slot :elem, required: true, doc: "Value for each element of the list" do
     attr :label, :string, required: true, doc: "Label for the elem"
   end
@@ -792,7 +800,7 @@ defmodule Phoenix.LiveDashboard.PageBuilder do
   attr :title, :string, required: true, doc: "Title of the modal"
 
   attr :return_to, :string, required: true, doc: "Path to return when closing the modal"
-  slot(:inner_block, required: true, doc: "Content to show in the modal")
+  slot :inner_block, required: true, doc: "Content to show in the modal"
 
   def live_modal(assigns) do
     ~H"""
diff --git a/mix.exs b/mix.exs
index d2a73546..f40aa673 100644
--- a/mix.exs
+++ b/mix.exs
@@ -85,7 +85,10 @@ defmodule Phoenix.LiveDashboard.MixProject do
       source_url: "https://github.com/phoenixframework/phoenix_live_dashboard",
       extra_section: "GUIDES",
       extras: extras(),
-      nest_modules_by_prefix: [Phoenix.LiveDashboard]
+      nest_modules_by_prefix: [Phoenix.LiveDashboard],
+      groups_for_functions: [
+        Components: &(&1[:type] == :component)
+      ]
     ]
   end