List of 1.7.0 RC 0 documentation defects

[CharlesIrvine]

I’m going through the Phoenix 1.7.0 rc 0 version of the Phoenix guides. I’ve seen a few documentation defects so far. Should I log GitHub issues for these?

[arcyfelix]

Please present the defects here and the community will help. Chris is an active member here as well as far as I have seen so it is worth a try.

[LostKobrakai]

Before reporting problems somewhere it’s also a good idea to see if they problems are not yet fixed on the master branch or if there are PRs to fixing them already. The more time goes on since the rc being released the more likely it’ll be things have already been handled.

[CharlesIrvine]

At Up and Running — Phoenix v1.7.0-rc.0 the out-of-the-box “/” route is incorrect:

[CharlesIrvine]

At Request life-cycle — Phoenix v1.7.0-rc.0, in section “A new route”, the out-of-the-box (OOTB) route is incorrectly given as:

get “/”, PageController, :index

The actual OOTB route is:

git “/”, PageController, :home

[CharlesIrvine]

At Request life-cycle — Phoenix v1.7.0-rc.0 in section “A new view” the guide is inconsistent in the naming of the templates directory.

In module HelloWeb.HelloHTML it is given as “hello”:

In the directions to create the template it is given as “hello_html”:

[CharlesIrvine]

At Request life-cycle — Phoenix v1.7.0-rc.0 two code snippets use a css class name that aren’t defined - “phx-hero”:

<section class="phx-hero">
  <h2>Hello World, from <%= @messenger %>!</h2>
</section>

and:

<section class="phx-hero">
  <h2>Hello World, from Phoenix!</h2>
</section>

Since the class isn’t defined the associated guide screen shots are inaccurate. For example:

[AstonJ]

Hi @CharlesIrvine, I’ve merged all your threads into this one as it will be easier to track that way

[CharlesIrvine]

Good idea. Thanks

[kokolegorille]

It does not look like the home page of Phoenix 1.7 version…

Are You sure You did not build a 1.6 version?

It should have a tailwind look, which is very different

In fact, viewing the changelog on your screenshot… You are on 1.4!

[CharlesIrvine]

@kokolegorille , the screen shot shown is the one that shows in the 1.7 guides. And that was my point, that is, it’s not the right screen shot for version 1.7. The docs need to be updated to show the latest screen show.

[kokolegorille]

ah ok… i thought it was your dev server

[CharlesIrvine]

At Routing — Phoenix v1.7.0-rc.0 in section “Verified Routes”, the sample code for module RouteExample uses a module, GenTestWeb, that won’t defined the the sample HelloWeb app:

defmodule RouteExample do
  use GenTestWeb, :verified_routes

  def example do
    ~p"/comments"
    ~p"/unknown/123"
  end
end
warning: no route path for GenTestWeb.Router matches "/unknown/123"
  iex:5: RouteExample.example/0

{:module, RouteExample, ...}

Instead the example should use the module HelloWeb:

defmodule RouteExample do
  use HelloWeb, :verified_routes

  def example do
    ~p"/comments"
    ~p"/unknown/123"
  end
end
warning: no route path for GenTestWeb.Router matches "/unknown/123"
  iex:5: RouteExample.example/0

{:module, RouteExample, ...}

[cmo]

I would just raise them as issues mate. The maintainers will be very appreciative.

[CharlesIrvine]

Problem #1

In the Phoenix guides at: Controllers — Phoenix v1.7.0-rc.0 in the section “Assigning layouts”, instructions are given for modifying the :index action of PageController to be:

def index(conn, _params) do
  conn
  |> put_root_layout(false)
  |> render(:index)
end

However, the phx.new command no longer generates an :index action. Instead it generates the :home action:

defmodule HelloWeb.PageController do
  use HelloWeb, :controller

  def home(conn, _params) do
    conn
    |> put_root_layout(false)
    |> render(:home)
  end
end

So, either the guide should be updated to specify the :home action, or phx.new should be updated to generate the :index action.

Problem #2

The documentation states that after modifying the auto generated action for PageController as described in the “Assigning layouts” section and redisplaying the “/” route, a blank page should be displayed. This doesn’t happen. The page displayed is:

[CharlesIrvine]

In the Phoenix 1.7 guides at: Components and HEEx Templates — Phoenix v1.7.0-rc.0 in section " Rendering templates from the controller", the reader is instructed to add a title/0 function to HelloWeb.Layouts, by updating the file to:

defmodule HelloWeb.Layouts do
  use HelloWeb, :view

  attr :suffix, default: nil

  def title(assigns) do
    ~H"""
    Welcome to HelloWeb! <%= @suffix %>
    """
  end
end

I believe that:

use HelloWeb, :view

is incorrect and that the corrected line should be:

use HelloWeb, :html

Problem #2

I think the line:

attr :suffix, default: nil

should instead be:

attr :suffix, :string, default: nil

[CharlesIrvine]

If any of maintainers are reading this post, let me know if you would prefer that I enter each of these as GitHub issues. Thanks

[joey_the_snake]

I usually see people submit a PR for cases like this. I feel like you could open one with the fixes you’re confident about and it will get looked at faster than here. Just make sure they haven’t been fixed in the main branch before submitting so it’s not wasting their time.