diff --git a/pkgs/development/interpreters/ruby/load-ruby-env.nix b/pkgs/development/interpreters/ruby/load-ruby-env.nix
index f1c9f71f51c..1a28e1cd047 100644
--- a/pkgs/development/interpreters/ruby/load-ruby-env.nix
+++ b/pkgs/development/interpreters/ruby/load-ruby-env.nix
@@ -1,5 +1,31 @@
 { ruby, lib, callPackage, gemFixes, fetchurl, buildRubyGem }@defs:
 
+# This function builds a set of gems. You first convert your Gemfile to an attrset
+# called a "gemset", and then use this function to build the gemset.
+#
+# A gemset looks like the following:
+#
+#   {
+#     libv8 = {
+#       version = "3.16.14.7";
+#       src = {
+#         type = "gem";
+#         sha256 = "...";
+#       };
+#     };
+#     therubyracer = {
+#       version = "0.12.1";
+#       dependencies = [ "libv8" ];
+#       src = {
+#         type = "gem";
+#         sha256 = "...";
+#       };
+#     };
+#   }
+#
+# If you use these gems as build inputs, the GEM_PATH will be updated
+# appropriately, and command like `bundle exec` should work out of the box.
+
 { gemset, ruby ? defs.ruby, fixes ? gemFixes }@args:
 
 let