Add a bit of javadoc

src/main/java/org/jline/terminal/Terminal.java

@@ -18,6 +18,12 @@
 import org.jline.utils.InfoCmp.Capability;
 import org.jline.utils.NonBlockingReader;
 
+/**
+ * A terminal representing a virtual terminal on the computer.
+ *
+ * Terminals should be closed by calling the {@link #close()} method
+ * in order to restore their original state.
+ */
 public interface Terminal extends Closeable, Flushable {
 
     String getName();

src/main/java/org/jline/terminal/TerminalBuilder.java

@@ -29,12 +29,26 @@
 import org.jline.utils.Log;
 import org.jline.utils.OSUtils;
 
+/**
+ * Builder class to create terminals.
+ */
 public final class TerminalBuilder {
 
+    /**
+     * Returns the default system terminal.
+     * Terminals should be closed properly using the {@link Terminal#close()}
+     * method in order to restore the original terminal state.
+     *
+     * This call is equivalent to:
+     * <code>builder().build()</code>
+     */
     public static Terminal terminal() throws IOException {
         return builder().build();
     }
 
+    /**
+     * Creates a new terminal builder instance.
+     */
     public static TerminalBuilder builder() {
         return new TerminalBuilder();
     }