[Feature Request] Add `annotaterb controllers` to comment controller actions

[pioz]

Description
Currently, annotaterb provides annotations for models and routes of a Rails application. It would be incredibly useful to have a dedicated command (e.g., annotaterb controllers) that automatically inserts comments for each controller action. This feature would mimic the style and functionality of the default Rails scaffold, which generates annotations/comments for the actions created by a scaffolded controller.

Use Case

• When working on multiple controllers, it’s often helpful to have a quick reference to what each action does or which parameters are expected.
• Developers new to a codebase can quickly understand the structure and purpose of each action.
• Standardizing annotations across models, views, and controllers would improve consistency and readability.

Proposed Approach

1. Add CLI Option
   • Introduce a new option annotaterb controllers that developers can run to annotate all controllers in the app/controllers directory.
2. Annotation Format
   • Follow a format similar to Rails scaffold comments (e.g., # GET /users, # POST /users, etc.).
   • Include relevant details about the params each action expects or provides, similar to how model annotations show column information (?).
3. Integration with Existing Commands
   • Consider providing an annotaterb all command to include both model and controller annotations in a single command if desired.

Example
Below is a simplified example of the type of comments you might expect in a classic Rails CRUD controller for Posts:

class PostsController < ApplicationController
  before_action :set_post, only: %i[ show edit update destroy ]

  # GET /posts
  # GET /posts.json
  def index
    @posts = Post.all
  end

  # GET /posts/:id
  # GET /posts/:id.json
  def show
  end

  # GET /posts/new
  def new
    @post = Post.new
  end

  # GET /posts/1/edit
  def edit
  end

  # POST /posts
  # POST /posts.json
  def create
    @post = Post.new(post_params)

    respond_to do |format|
      if @post.save
        format.html { redirect_to @post, notice: "Post was successfully created." }
        format.json { render :show, status: :created, location: @post }
      else
        format.html { render :new, status: :unprocessable_entity }
        format.json { render json: @post.errors, status: :unprocessable_entity }
      end
    end
  end

  # PATCH/PUT /posts/:id
  # PATCH/PUT /posts/:id.json
  def update
    respond_to do |format|
      if @post.update(post_params)
        format.html { redirect_to @post, notice: "Post was successfully updated." }
        format.json { render :show, status: :ok, location: @post }
      else
        format.html { render :edit, status: :unprocessable_entity }
        format.json { render json: @post.errors, status: :unprocessable_entity }
      end
    end
  end

  # DELETE /posts/:id
  # DELETE /posts/:id.json
  def destroy
    @post.destroy!

    respond_to do |format|
      format.html { redirect_to posts_path, status: :see_other, notice: "Post was successfully destroyed." }
      format.json { head :no_content }
    end
  end

  private
    # Use callbacks to share common setup or constraints between actions.
    def set_post
      @post = Post.find(params.expect(:id))
    end

    # Only allow a list of trusted parameters through.
    def post_params
      params.expect(post: [ :title, :body ])
    end
end

Thank you for considering this feature request!

[G-Rath]

fwiw this sounds like what chusaku does - personally, I think it would make sense to have a single "annotation" gem that does all these things for ease-of-use, but that would be something the maintainers would need to agree on and coordinate

[drwl]

Hi @pioz it seems like @G-Rath mentioned about another gem that exists to solve this issue. Have you given it a try?

The ask, being able to have various Rails functionality annotated in one gem, seems reasonable, but I also think it makes sense to keep them separate. Also, chusaku gem seems to be actively maintained.

I'm going to have to decline this feature request for now to prevent feature creep and also I won't have time in the foreseeable future to add or maintain that additional set of functionality.