We would like to have better documentation for Rack.

Many hands make light work.

Step 1: Find a method without documentation:

Start in this directory: https://github.com/rack/rack/tree/main/lib/rack

Choose a file at random and look for a method without documentation that you think you can figure out.

Double check there isn't a PR already for this method. PRs should follow Documentation for MyClass#my_method and have the Documentation label.

Press the "." button on your keyboard to open the GH editor.

Step 2: Add documentation.

Follow the RDoc format, and if you think it's appropriate, start with a :call-seq:.

# :call-seq:
#   my_method(argument) -> return value/type

For the initial call sequence, just copy the method name and all arguments.

Explain what the method does, how it relates to other methods. Method names will link in RDoc, so if you write:

# This method calls other_method

It will automatically link other_method. Don't add + characters or any other formatting around it or it might break auto-linking.

For classes/modules internal to the documentation, just write:

# See MyClass for more details.

It will automatically link MyClass.

For external classes, like, say String or Hash, use +String+ and +Hash+ for monospace font. Same for variables/argument names, e.g.

# The argument should be either a String or Hash.

Look at examples of existing documentation for best practice (or not!!).

Step 3: Submit Pull Request

Submit the pull request directly from the editor. Format the title like this:

Documentation for {MyClass#my_method}.

Make sure the PR has the documentation label.

Be prepared to handle incoming feedback or clarifications from Rack maintainers. We hope everyone will be kind and attentive to making Rack documentation better. If you have any issues please feel free to ping me @ioquatix.