Add documentation

Author: nicolasstucki

library/src/scala/annotation/MainAnnotation.scala

@@ -7,22 +7,56 @@ package scala.annotation
  *
  *    - create a `command` with the command line arguments,
  *    - for each parameter of user-main, a call to `command.argGetter`,
- *      or `command.argsGetter` if is a final varargs parameter,
+ *      or `command.varargGetter` if is a final varargs parameter,
  *    - a call to `command.run` with the closure of user-main applied to all arguments.
+ *
+ *  Example:
+ *  ```scala
+ *  /** Sum all the numbers
+ *   *
+ *   *  @param first Fist number to sum
+ *   *  @param rest The rest of the numbers to sum
+ *   */
+ *  @myMain def sum(first: Int, rest: Int*): Int = first + rest.sum
+ *  ```
+ *  generates
+ *  ```scala
+ *  object foo {
+ *    def main(args: Array[String]): Unit = {
+ *      val cmd = new myMain().command(
+ *        args = args,
+ *        commandName = "sum",
+ *        documentation = "Sum all the numbers",
+ *        new ParameterInfo("first", "scala.Int", hasDefault=false, isVarargs=false, "Fist number to sum"),
+ *        new ParameterInfo("rest", "scala.Int" , hasDefault=false, isVarargs=true, "The rest of the numbers to sum")
+ *      )
+ *      val args0 = cmd.argGetter[Int](0, None) // using cmd.Parser[Int]
+ *      val args1 = cmd.varargGetter[Int] // using cmd.Parser[Int]
+ *      cmd.run(() => sum(args0(), args1()*))
+ *    }
+ *  }
+ *  ```
  */
 @experimental
 trait MainAnnotation extends StaticAnnotation:
   import MainAnnotation.*
 
-  /** The class used for argument string parsing. E.g. `scala.util.CommandLineParser.FromString`,
-   *  but could be something else
-   */
+  /** The class used for argument string parsing and arguments into a `T` */
   type Parser[T]
 
-  /** The required result type of the main function */
+  /** The required result type of the main method.
+   *
+   *  If this type is Any or Unit, any type will be accepted.
+   */
   type Result
 
-  /** A new command with arguments from `args` */
+  /** A new command with arguments from `args`
+   *
+   *  @param args The command line arguments
+   *  @param commandName The name of the command (name of the annotated method)
+   *  @param documentation The documentation of the command (without the `@param` documentation)
+   *  @param parameterInfos Information about all the parameters (name, type, has default, is varargs and documentation)
+   */
   def command(args: Array[String], commandName: String, documentation: String, parameterInfos: ParameterInfo*): Command[Parser, Result]
 
 end MainAnnotation
@@ -39,7 +73,14 @@ object MainAnnotation:
     paramAnnotations: Seq[ParameterAnnotation],
   ) {
 
-    /** ParameterInfo with a name, the type of the parameter and if it has a default */
+    /** ParameterInfo with a name, the type of the parameter and if it has a default
+     *
+     *  @param name The name of the parameter
+     *  @param typeName The type of the parameter
+     *  @param hasDefault If the parameter has a default argument
+     *  @param isVarargs If the parameter is a varargs parameter (can only be true for the last parameter)
+     *  @param documentation The documentation of the parameter (from `@param` documentation in the main method)
+     */
     def this(name: String, typeName: String, hasDefault: Boolean, isVarargs: Boolean, documentation: String) =
       this(name, typeName, hasDefault, isVarargs, documentation, Seq.empty)
 
@@ -49,7 +90,7 @@ object MainAnnotation:
     /** The name of the parameter's type */
     def typeName: String = paramTypeName
 
-    /** If the parameter has a default value */
+    /** If the parameter has a default argument */
     def hasDefault: Boolean = paramHasDefault
 
     /** If this is a varargs parameter. Can only be true if it is the last parameter. */
@@ -71,14 +112,19 @@ object MainAnnotation:
   /** A class representing a command to run */
   trait Command[Parser[_], Result]:
 
-    /** The getter for the `idx`th argument of type `T` */
+    /** The getter for the `idx`th argument of type `T`
+     *
+     *   @param idx The index of the argument
+     *   @param defaultArgument Optional lambda to instantiate the default argument
+     */
     def argGetter[T](idx: Int, defaultArgument: Option[() => T])(using Parser[T]): () => T
 
     /** The getter for a final varargs argument of type `T*` */
     def varargGetter[T](using Parser[T]): () => Seq[T]
 
-    /** Run `program` if all arguments are valid,
-     *  or print usage information and/or error messages.
+    /** Run `program` if all arguments are valid if all arguments are valid
+     *
+     *  @param program A function containing the call to the main method and instantiation of its arguments
      */
     def run(program: () => Result): Unit
   end Command