Add documentation on classes / models

[tmaier]

It would be great to have some code-level comments to explain a bit the architecture.

For example what the purpose of certain classes. For example, why is there a Session model.

This could help to understand the chosen architecture and helps a future developer to pick this up more quickly.

[lazaronixon]

That's a good idea. I would like to have some comments, like in the rails scaffold. Can you submit something?

[drewhoffer]

Don't mind taking a swing at a couple as I go through with building my app and adding as I come across. Can you give me an example of where to start for doing this @lazaronixon as well as what format you would like to see?

[lazaronixon]

I didn't make up my mind about this. But some topics to consider:

• Take inspiration on rails scaffolds.
• Comments in the controllers for sure.
• I wonder if we should document models. I would have to see what it looks like first.
• Only document the default generator (without options) and --api.
• Reference methods that are not so common to the API rails documentation. so people can learn more.

[drewhoffer]

I will take a look this week and put some PR's up after work.

[drewhoffer]

Sorry for the delay on this.

I'm both finding a lot and a little on how others do commenting for their Rails apps (most posts are excess of 10 years old).

How do we feel about a brief comment explaining most of the high-level purpose/functionality with something like the following:

class RegistrationsController < ApplicationController
  # Skip the authentication before action for this controller
  skip_before_action :authenticate

  # Action to render the sign-up form
  def new
    @user = User.new
  end

  # Action to handle the sign-up form submission
  def create
    @user = User.new(user_params)

    if @user.save
      # Create a new session for the user
      session_record = @user.sessions.create!
      # Set a signed, permanent cookie with the session token
      cookies.signed.permanent[:session_token] = { value: session_record.id, httponly: true }

      # Send an email verification to the user
      send_email_verification
      # Redirect to the root path with a success notice
      redirect_to root_path, notice: "Welcome! You have signed up successfully"
    else
      # Render the sign-up form again with an unprocessable entity status
      render :new, status: :unprocessable_entity
    end
  end

  private

  # Strong parameters for user sign-up
  def user_params
    params.permit(:email, :password, :password_confirmation)
  end

  # Method to send an email verification to the user
  def send_email_verification
    UserMailer.with(user: @user).email_verification.deliver_later
  end
end

Example is from the registraion html template.

[lazaronixon]

There are too many comments... I would like:

• Only method level, no comments inside.
• They must be easy to delete.
• Map routes are just enough.
• Comments in the generator should teach, not explain.

[drewhoffer]

Ok so taking my original example we are looking for more of the literal rails scaffold comments.

class RegistrationsController < ApplicationController
  skip_before_action :authenticate

  # GET /sign_up
  def new
    @user = User.new
  end

  # POST /sign_up
  def create
    @user = User.new(user_params)

    if @user.save
      session_record = @user.sessions.create!
      cookies.signed.permanent[:session_token] = { value: session_record.id, httponly: true }

      send_email_verification
      redirect_to root_path, notice: "Welcome! You have signed up successfully"
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  # Only allow a list of trusted parameters through.
  def user_params
    params.permit(:email, :password, :password_confirmation)
  end

  # Method to send an email verification to the user
  def send_email_verification
    UserMailer.with(user: @user).email_verification.deliver_later
  end
end

As an aside, I think it would be best I do these in batches. So, for now I'll focus on just the controllers for a first PR and once that's done I can move onto models, etc.