Improve documentation

Author: eregon

src/main/java/org/truffleruby/language/arguments/ArgumentsDescriptor.java

@@ -9,8 +9,9 @@
  */
 package org.truffleruby.language.arguments;
 
-/** An arguments descriptor is an object that describes something about the arguments being passed. Argument descriptors
- * are stable, immutable objects, suitable to be cached and guarded by identity. They'd normally convey some kind of
- * static information from call site to callee. */
+/** An arguments descriptor describes what kind of arguments are passed at a given call site. Most importantly they
+ * describe whether some keywords arguments are passed or none. Argument descriptors are stable, immutable objects,
+ * suitable to be cached and guarded by identity. They'd normally convey some kind of static information from call site
+ * to callee. */
 public abstract class ArgumentsDescriptor {
 }

src/main/java/org/truffleruby/language/arguments/EmptyArgumentsDescriptor.java

@@ -9,7 +9,7 @@
  */
 package org.truffleruby.language.arguments;
 
-/** An arguments descriptor that says that it is not know if there are keyword arguments. */
+/** An argument descriptor that says no keyword arguments were passed (only positional arguments). */
 public class EmptyArgumentsDescriptor extends ArgumentsDescriptor {
 
     public static final EmptyArgumentsDescriptor INSTANCE = new EmptyArgumentsDescriptor();

src/main/java/org/truffleruby/language/arguments/KeywordArgumentsDescriptor.java

@@ -9,7 +9,9 @@
  */
 package org.truffleruby.language.arguments;
 
-/** An arguments descriptor that says that keyword arguments are present. */
+/** An arguments descriptor that says that keyword arguments were passed (either foo(a: 1) or foo(**kw)). Note that
+ * currently, if kw is empty, then this descriptor is used even though it is semantically the same as if no keyword
+ * arguments were passed. The callee must handle that for now. */
 public class KeywordArgumentsDescriptor extends ArgumentsDescriptor {
 
     public static final KeywordArgumentsDescriptor INSTANCE = new KeywordArgumentsDescriptor();