Package com.jagrosh.jdautilities.doc

Class DocGenerator

java.lang.Object
com.jagrosh.jdautilities.doc.DocGenerator
public class DocGenerator extends Object
An instance based documentation engine for bot commands written in JDA.

Instances of this can read Annotations on Classes and/or Methods to format and document the command's they represent.

The most basic usage of this can be shown below: 

   @CommandInfo(
     name = {"MyCommand", "MC"},
     usage = "MyCommand <Usage>",
     description = "This is an example of CommandDoc's standard @CommandInfo annotation"
 )
 public class MyCommand {
     // ...
 }
Then... 

     DocGenerator generator = DocGenerator.getDefaultGenerator();
     String documentation = generator.getDocForClass(MyCommand.class);

Note: This documentation system is universal, can be applied to any command system that uses Class and/or Method based commands, and works in any JVM language that supports annotations.

Since:
2.0
Author:
Kaidan Gustave
See Also:

  • Constructor Details

    • DocGenerator

      public DocGenerator()
      Gets a blank DocGenerator with no conversions loaded.

    • DocGenerator

      public DocGenerator(int cacheSize)
      Gets a blank DocGenerator with no conversions loaded, and a cache with the specified max-size.

      Calls to getDocFor(java.lang.Class), getDocFor(java.lang.reflect.Method), and getDocForMethods(java.lang.Class) also cache the values retrieved from the invocation as a way to reduce reflection overhead for repeated calls.

      Parameters:
      cacheSize - The of the cache size that contains previously generated CommandDoc to reduce reflection overhead for repeated calls.

    • DocGenerator

      public DocGenerator(String separator, int cacheSize)
      Gets a blank DocGenerator with no conversions loaded and with the specified separator, and a cache with the specified max-size.

      A separator will be appended to the documentation returned by getDocFor(java.lang.Class) inbetween annotation conversions.
      By default this is a double newline (\n\n).

      Calls to getDocFor(java.lang.Class), getDocFor(java.lang.reflect.Method), and getDocForMethods(java.lang.Class) also cache the values retrieved from the invocation as a way to reduce reflection overhead for repeated calls.

      Parameters:
      separator - The separator that occurs inbetween annotation conversions.
      cacheSize - The of the cache size that contains previously generated CommandDoc to reduce reflection overhead for repeated calls.

  • Method Details

    • getDefaultGenerator

      public static DocGenerator getDefaultGenerator()
      Gets a default DocGenerator with standard conversions loaded.

      This is the simplest way to get a prebuilt working CommandDoc generator with standard annotations.

      Additional annotations can be added using register(Class, Object...).

      Returns:
      The default DocGenerator with standard conversions loaded.

    • getDocFor

      public String getDocFor(Class<?> cla)
      Reads CommandDoc from the provided Class and returns the String formatted and from it.
      Parameters:
      cla - The Class to get CommandDoc from.
      Returns:
      The documentation read from the Class.

    • getDocFor

      public String getDocFor(Method method)
      Reads CommandDoc from the provided Method and returns the String formatted and from it.
      Parameters:
      method - The Method to get CommandDoc from.
      Returns:
      The documentation read from the Method.

    • getDocForMethods

      public List<String> getDocForMethods(Class<?> cla)
      Reads all Methods from the provided Class and returns a List of CommandDoc of each.

      Methods read that return empty Strings are not added to the list.

      Parameters:
      cla - The Class to get CommandDoc from each method
      Returns:
      A List of individual Method CommandDocs

    • register

      public <T extends Annotation> DocGenerator register(Class<T> type, Object... converterParams)
      Registers a CommandDoc Annotation to this DocGenerator.

      An example of a custom CommandDoc conversion annotation can be found in the DocConverter documentation.

      Type Parameters:
      T - The type of annotation
      Parameters:
      type - The annotation Class type.
      converterParams - The parameters necessary to instantiate the proper DocConverter.
      DocConverters can have multiple constructors, although it's discouraged.
      Returns:
      This DocGenerator
      Throws:
      IllegalArgumentException - The annotation class provided is not annotated with @ConvertedBy, or an exception is thrown while instantiating the value said ConvertedBy annotation.
      NOTE: that a DocConverter instantiation will fail if it's type parameter is the provided Annotation class.

    • register

      public <T extends Annotation> DocGenerator register(Class<T> type, DocConverter<T> converter)
      Registers a CommandDoc Annotation to this DocGenerator with the provided DocConverter.

      This is not recommended unless you for some reason want to pass an instance variable to the DocConverter you are providing.

      An example of a custom CommandDoc conversion annotation can be found in the DocConverter documentation.

      Type Parameters:
      T - The type of annotation.
      Parameters:
      type - The annotation Class type.
      converter - The DocConverter to use.
      Returns:
      This DocGenerator