Repository: phoenixframework/phoenix
Pull request #4914 (2022-08-12 15:38:40)

Put the overview guides link top of moduledoc
I had people today that were discovering Phoenix and just thought that this was the main hub as it was linked as "Docs" from the phoenixframework.org website. I think that for a newcomer that end up there, having the guide link at the top probably would make more sense.


Patch:
diff --git a/.formatter.exs b/.formatter.exs
index 3887f7a3e..417d8f00c 100644
--- a/.formatter.exs
+++ b/.formatter.exs
@@ -63,9 +63,12 @@ locals_without_parens = [
   # Phoenix.ConnTest
   assert_error_sent: 2,
 
-  # Phoenix.Live{Dashboard,View}.Router
+  # Phoenix.Live{Dashboard,View}
   attr: 2,
   attr: 3,
+  slot: 1,
+  slot: 2,
+  slot: 3,
   live: 2,
   live: 3,
   live: 4,
diff --git a/installer/lib/mix/tasks/phx.new.ex b/installer/lib/mix/tasks/phx.new.ex
index 7e05988c2..6be2adab7 100644
--- a/installer/lib/mix/tasks/phx.new.ex
+++ b/installer/lib/mix/tasks/phx.new.ex
@@ -211,6 +211,7 @@ defmodule Mix.Tasks.Phx.New do
     maybe_cmd(project, "mix deps.get", true, install? && hex_available?())
   end
 
+  # TODO: Elixir v1.15 automatically installs Hex/Rebar if missing, so we can simplify this.
   defp hex_available? do
     Code.ensure_loaded?(Hex)
   end
diff --git a/installer/lib/phx_new/generator.ex b/installer/lib/phx_new/generator.ex
index 70a99887c..f5f339831 100644
--- a/installer/lib/phx_new/generator.ex
+++ b/installer/lib/phx_new/generator.ex
@@ -191,7 +191,6 @@ defmodule Phx.New.Generator do
     version = @phoenix_version
 
     binding = [
-      elixir_version: elixir_version(),
       app_name: project.app,
       app_module: inspect(project.app_mod),
       root_app_name: project.root_app,
@@ -227,10 +226,6 @@ defmodule Phx.New.Generator do
     %Project{project | binding: binding}
   end
 
-  defp elixir_version do
-    System.version()
-  end
-
   defp namespaced?(project) do
     Macro.camelize(project.app) != inspect(project.app_mod)
   end
diff --git a/installer/templates/phx_single/lib/app_name_web.ex b/installer/templates/phx_single/lib/app_name_web.ex
index 09fcd5e9e..14f0ec2b1 100644
--- a/installer/templates/phx_single/lib/app_name_web.ex
+++ b/installer/templates/phx_single/lib/app_name_web.ex
@@ -80,13 +80,6 @@ defmodule <%= @web_namespace %> do
     end
   end
 
-  def channel do
-    quote do
-      use Phoenix.Channel<%= if @gettext do %>
-      import <%= @web_namespace %>.Gettext<% end %>
-    end
-  end
-
   def verified_routes do
     quote do
       use Phoenix.VerifiedRoutes,
@@ -96,22 +89,28 @@ defmodule <%= @web_namespace %> do
     end
   end
 
+  def channel do
+    quote do
+      use Phoenix.Channel<%= if @gettext do %>
+      import <%= @web_namespace %>.Gettext<% end %>
+    end
+  end
+
   defp view_helpers do
     quote do<%= if @html do %>
-      # Use all HTML functionality (forms, tags, etc)
+      # Import basic HTML rendering capabilities (tags, forms, etc)
       use Phoenix.HTML
 
-      # Import and alias LiveView and .heex helpers (live_render, <.link>, <.form>, etc)
+      # Import .heex helpers (<.link>, <.form>, etc) and alias JS module
       import Phoenix.LiveView.Helpers
       alias Phoenix.LiveView.JS
 <% end %>
-      # Import basic rendering functionality (render, render_layout, etc)
-      import Phoenix.View
+      # Include the router functionality defined above
+      unquote(verified_routes())
 
+      # All imports from the current project should be defined from here under
       import <%= @web_namespace %>.ErrorHelpers<%= if @gettext do %>
-      import <%= @web_namespace %>.Gettext<% end %><%= if @html do %>
-      alias Phoenix.LiveView.JS<% end %>
-      unquote(verified_routes())
+      import <%= @web_namespace %>.Gettext<% end %>
     end
   end
 
diff --git a/installer/templates/phx_umbrella/apps/app_name_web/lib/app_name.ex b/installer/templates/phx_umbrella/apps/app_name_web/lib/app_name.ex
index 86cf4a8f4..2fac732fa 100644
--- a/installer/templates/phx_umbrella/apps/app_name_web/lib/app_name.ex
+++ b/installer/templates/phx_umbrella/apps/app_name_web/lib/app_name.ex
@@ -81,13 +81,6 @@ defmodule <%= @web_namespace %> do
     end
   end
 
-  def channel do
-    quote do
-      use Phoenix.Channel<%= if @gettext do %>
-      import <%= @web_namespace %>.Gettext<% end %>
-    end
-  end
-
   def verified_routes do
     quote do
       use Phoenix.VerifiedRoutes,
@@ -97,22 +90,28 @@ defmodule <%= @web_namespace %> do
     end
   end
 
+  def channel do
+    quote do
+      use Phoenix.Channel<%= if @gettext do %>
+      import <%= @web_namespace %>.Gettext<% end %>
+    end
+  end
+
   defp view_helpers do
     quote do<%= if @html do %>
-      # Use all HTML functionality (forms, tags, etc)
+      # Import basic HTML rendering capabilities (tags, forms, etc)
       use Phoenix.HTML
 
-      # Import and alias LiveView and .heex helpers (live_render, <.link>, <.form>, etc)
+      # Import .heex helpers (<.link>, <.form>, etc) and alias JS module
       import Phoenix.LiveView.Helpers
       alias Phoenix.LiveView.JS
 <% end %>
-      # Import basic rendering functionality (render, render_layout, etc)
-      import Phoenix.View
+      # Include the router functionality defined above
+      unquote(verified_routes())
 
+      # All imports from the current project should be defined from here under
       import <%= @web_namespace %>.ErrorHelpers<%= if @gettext do %>
-      import <%= @web_namespace %>.Gettext<% end %><%= if @html do %>
-      alias Phoenix.LiveView.JS<% end %>
-      unquote(verified_routes())
+      import <%= @web_namespace %>.Gettext<% end %>
     end
   end
 
diff --git a/installer/templates/phx_web/router.ex b/installer/templates/phx_web/router.ex
index 79c1b2407..5a1801785 100644
--- a/installer/templates/phx_web/router.ex
+++ b/installer/templates/phx_web/router.ex
@@ -44,7 +44,7 @@ defmodule <%= @web_namespace %>.Router do
 
       live_dashboard "/dashboard", metrics: <%= @web_namespace %>.Telemetry
     end
-  <% end %><%= if @mailer do %>
+<% end %><%= if @mailer do %>
     scope "/dev" do<%= if @html do %>
       pipe_through :browser<% else %>
       pipe_through [:fetch_session, :protect_from_forgery]<% end %>
diff --git a/lib/mix/tasks/compile.phoenix.ex b/lib/mix/tasks/compile.phoenix.ex
index 40d537fbf..a484a39ca 100644
--- a/lib/mix/tasks/compile.phoenix.ex
+++ b/lib/mix/tasks/compile.phoenix.ex
@@ -2,7 +2,6 @@ defmodule Mix.Tasks.Compile.Phoenix do
   use Mix.Task
   @recursive true
   @moduledoc false
-  @mix_recompile Version.match?(System.version(), ">= 1.11.0")
 
   @doc false
   def run(_args) do
@@ -46,7 +45,7 @@ defmodule Mix.Tasks.Compile.Phoenix do
     function_exported?(mod, :__phoenix_recompile__?, 0) and mod.__phoenix_recompile__?()
   end
 
-  if @mix_recompile do
+  if Version.match?(System.version(), ">= 1.11.0") do
     # Recompile is provided by Mix, we don't need to do anything
     defp mix_recompile?(_mod), do: false
   else
diff --git a/lib/phoenix.ex b/lib/phoenix.ex
index fff4b85c1..5038f8ba3 100644
--- a/lib/phoenix.ex
+++ b/lib/phoenix.ex
@@ -2,6 +2,8 @@ defmodule Phoenix do
   @moduledoc """
   This is the documentation for the Phoenix project.
 
+  To get started, see our [overview guides](overview.html).
+  
   By default, Phoenix applications depend on the following packages
   across these categories.
 
@@ -44,7 +46,6 @@ defmodule Phoenix do
     * [Telemetry Metrics](https://hexdocs.pm/telemetry_metrics) - common
       interface for defining metrics based on Telemetry events
 
-  To get started, see our [overview guides](overview.html).
   """
   use Application
 
diff --git a/lib/phoenix/channel.ex b/lib/phoenix/channel.ex
index ea60fccba..1e475b28c 100644
--- a/lib/phoenix/channel.ex
+++ b/lib/phoenix/channel.ex
@@ -5,6 +5,8 @@ defmodule Phoenix.Channel do
   Channels provide a means for bidirectional communication from clients that
   integrate with the `Phoenix.PubSub` layer for soft-realtime functionality.
 
+  For a conceptual overview, see the [Channels guide](channels.html).
+
   ## Topics & Callbacks
 
   Every time you join a channel, you need to choose which particular topic you
diff --git a/lib/phoenix/digester.ex b/lib/phoenix/digester.ex
index b06c08e9d..5e511cea0 100644
--- a/lib/phoenix/digester.ex
+++ b/lib/phoenix/digester.ex
@@ -83,7 +83,7 @@ defmodule Phoenix.Digester do
     write_manifest(latest, digests, output_path)
   end
 
-  @comment "This is file was auto-generated by `mix phx.digest`. Remove it and all generated artefacts with `mix phx.digest.clean --all`"
+  @comment "This file was auto-generated by `mix phx.digest`. Remove it and all generated artefacts with `mix phx.digest.clean --all`"
 
   defp write_manifest(latest, digests, output_path) do
     encoder = Phoenix.json_library()
diff --git a/lib/phoenix/verified_routes.ex b/lib/phoenix/verified_routes.ex
index 32be97e39..9af3117ba 100644
--- a/lib/phoenix/verified_routes.ex
+++ b/lib/phoenix/verified_routes.ex
@@ -4,7 +4,7 @@ defmodule Phoenix.VerifiedRoutes do
 
   Use of the `sigil_p` macro allows paths and URLs throughout your
   application to be compile-time verified against your Phoenix router(s).
-  For example the following path and URL usages:
+  For example, the following path and URL usages:
 
       <.link href={~p"/sessions/new"} method="post">Sign in</.link>
 
@@ -53,7 +53,7 @@ defmodule Phoenix.VerifiedRoutes do
       use Phoenix.VerifiedRoutes,
         router: AppWeb.Router,
         endpoint: AppWeb.Endpoint,
-        statics: ~(images)
+        statics: ~w(images)
 
   ## Usage
 
@@ -77,7 +77,7 @@ defmodule Phoenix.VerifiedRoutes do
 
   ## Tracking Warnings
 
-  All static path segments must start with forward slash and you must have a static segment
+  All static path segments must start with forward slash, and you must have a static segment
   between dynamic interpolations in order for a route to be verified without warnings.
   For example, the following path generates proper warnings
 
@@ -139,8 +139,10 @@ defmodule Phoenix.VerifiedRoutes do
     Module.put_attribute(mod, :phoenix_verified_statics, statics)
   end
 
+  @after_verify_supported Version.match?(System.version(), ">= 1.14.0-dev")
+
   defmacro __before_compile__(_env) do
-    if Version.match?(System.version(), ">= 1.14.0-dev") do
+    if @after_verify_supported do
       quote do
         @after_verify {__MODULE__, :__phoenix_verify_routes__}
 
@@ -712,7 +714,7 @@ defmodule Phoenix.VerifiedRoutes do
     {path_rewrite, query_rewrite} = verify_segment(segments, route, [])
 
     rewrite_route =
-      quote do
+      quote generated: true do
         query_str = unquote({:<<>>, meta, query_rewrite})
         path_str = unquote({:<<>>, meta, path_rewrite})
 
@@ -728,12 +730,12 @@ defmodule Phoenix.VerifiedRoutes do
     static? = static_path?(test_path, statics)
 
     path_ast =
-      quote do
+      quote generated: true do
         unquote(__MODULE__).unverified_path(unquote_splicing([endpoint, router, rewrite_route]))
       end
 
     static_ast =
-      quote do
+      quote generated: true do
         unquote(__MODULE__).static_path(unquote_splicing([endpoint, rewrite_route]))
       end
 


Test patch:
diff --git a/installer/test/phx_new_umbrella_test.exs b/installer/test/phx_new_umbrella_test.exs
index adb51be75..0d37b1cec 100644
--- a/installer/test/phx_new_umbrella_test.exs
+++ b/installer/test/phx_new_umbrella_test.exs
@@ -181,7 +181,7 @@ defmodule Mix.Tasks.Phx.New.UmbrellaTest do
       # assets
       assert_file web_path(@app, ".gitignore"), "/priv/static/assets/"
       assert_file web_path(@app, ".gitignore"), "#{@app}_web-*.tar"
-      assert_file web_path(@app, ".gitignore"),  ~r/\n$/
+      assert_file web_path(@app, ".gitignore"), ~r/\n$/
       assert_file web_path(@app, "assets/css/app.css")
       assert_file web_path(@app, "assets/css/phoenix.css")
 
@@ -745,7 +745,7 @@ defmodule Mix.Tasks.Phx.New.UmbrellaTest do
         assert_file "another/lib/another/templates/layout/app.html.heex"
 
         # assets
-        assert_file "another/.gitignore",  ~r/\n$/
+        assert_file "another/.gitignore", ~r/\n$/
         assert_file "another/priv/static/favicon.ico"
         assert_file "another/priv/static/images/phoenix.png"
         assert_file "another/assets/css/app.css"
diff --git a/priv/templates/phx.gen.html/controller_test.exs b/priv/templates/phx.gen.html/controller_test.exs
index df0c3b54a..a0bfa4d58 100644
--- a/priv/templates/phx.gen.html/controller_test.exs
+++ b/priv/templates/phx.gen.html/controller_test.exs
@@ -23,7 +23,7 @@ defmodule <%= inspect context.web_module %>.<%= inspect Module.concat(schema.web
 
   describe "create <%= schema.singular %>" do
     test "redirects to show when data is valid", %{conn: conn} do
-      conn = post(conn,  ~p"<%= schema.route_prefix %>", <%= schema.singular %>: @create_attrs)
+      conn = post(conn, ~p"<%= schema.route_prefix %>", <%= schema.singular %>: @create_attrs)
 
       assert %{id: id} = redirected_params(conn)
       assert redirected_to(conn) == ~p"<%= schema.route_prefix %>/#{id}"