Add java documentation iluwatar#324

mikulucky · mikulucky · commit c842f88eb74e · 2015-12-28T19:23:00.000Z
diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/AbstractPrinterController.java b/delegation/src/main/java/com/iluwatar/delegation/simple/AbstractPrinterController.java
@@ -1,13 +1,33 @@
 package com.iluwatar.delegation.simple;
 
-public abstract class AbstractPrinterController<T extends Printer> implements Printer{
+/**
+ * Extra layer of abstraction for the controller to allow the controller in this example {@link PrinterController} to
+ * be as clean as possible. This just provides the default constructor and a simple getter method. The generic of T allows
+ * any implementation of {@link Printer}
+ *
+ * @param <T> Printer
+ * @see Printer
+ * @see PrinterController
+ */
+public abstract class AbstractPrinterController<T extends Printer> implements Printer {
+
 
     private T printer;
 
+    /**
+     * @param printer instance of T {@link Printer} this instance is the delegate
+     */
     public AbstractPrinterController(T printer) {
         this.printer = printer;
     }
 
+    /**
+     * Helper method to return the current instance of T {@link Printer} in order for
+     * the controller to call operations on the {@link Printer}
+     *
+     * @return instance of Printer
+     * @see Printer
+     */
     protected T getPrinter() {
         return printer;
     }
diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/App.java b/delegation/src/main/java/com/iluwatar/delegation/simple/App.java
@@ -4,10 +4,22 @@
 import com.iluwatar.delegation.simple.printers.EpsonPrinter;
 import com.iluwatar.delegation.simple.printers.HPPrinter;
 
+/**
+ * In this example the delegates are {@link EpsonPrinter}, {@link HPPrinter} and {@link CanonPrinter} they all implement
+ * {@link Printer}. The {@link AbstractPrinterController} and through inheritance {@link PrinterController} also implement
+ * {@link Printer}. However neither provide the functionality of {@link Printer} by printing to the screen, they actually
+ * call upon the instance of {@link Printer} that they were instantiated with. Therefore delegating the behaviour to
+ * another class.
+ */
 public class App {
 
     public static final String MESSAGE_TO_PRINT = "hello world";
 
+    /**
+     * Program entry point
+     *
+     * @param args command line args
+     */
     public static void main(String[] args) {
         AbstractPrinterController hpPrinterController = new PrinterController(new HPPrinter());
         AbstractPrinterController canonPrinterController = new PrinterController(new CanonPrinter());
diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/Printer.java b/delegation/src/main/java/com/iluwatar/delegation/simple/Printer.java
@@ -1,6 +1,20 @@
 package com.iluwatar.delegation.simple;
 
+/**
+ *  Interface that both the Controller and the Delegate will implement.
+ *
+ *  @see com.iluwatar.delegation.simple.printers.CanonPrinter
+ *  @see com.iluwatar.delegation.simple.printers.EpsonPrinter
+ *  @see com.iluwatar.delegation.simple.printers.HPPrinter
+ *  @see AbstractPrinterController
+ */
 public interface Printer {
 
+    /**
+     * Method that takes a String to print to the screen. This will be implemented on both the
+     * controller and the delegate allowing the controller to call the same method on the delegate class.
+     *
+     * @param message to be printed to the screen
+     */
     void print(final String message);
 }
diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/PrinterController.java b/delegation/src/main/java/com/iluwatar/delegation/simple/PrinterController.java
@@ -6,6 +6,14 @@ public PrinterController(Printer printer) {
         super(printer);
     }
 
+    /**
+     * This method is implemented from {@link Printer} however instead on providing an
+     * implementation, it instead calls upon the class passed through the constructor. This is the delegate,
+     * hence the pattern. Therefore meaning that the caller does not care of the implementing class only the owning
+     * controller.
+     *
+     * @param message to be printed to the screen
+     */
     @Override
     public void print(String message) {
         getPrinter().print(message);
diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/CanonPrinter.java b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/CanonPrinter.java
@@ -2,8 +2,17 @@
 
 import com.iluwatar.delegation.simple.Printer;
 
+/**
+ * Specialised Implementation of {@link Printer} for a Canon Printer, in
+ * this case the message to be printed is appended to "Canon Printer : "
+ *
+ * @see Printer
+ */
 public class CanonPrinter implements Printer {
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void print(String message) {
         System.out.println("Canon Printer : " + message);
diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/EpsonPrinter.java b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/EpsonPrinter.java
@@ -2,8 +2,17 @@
 
 import com.iluwatar.delegation.simple.Printer;
 
+/**
+ * Specialised Implementation of {@link Printer} for a Epson Printer, in
+ * this case the message to be printed is appended to "Epson Printer : "
+ *
+ * @see Printer
+ */
 public class EpsonPrinter implements Printer{
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void print(String message) {
         System.out.println("Epson Printer : " + message);
diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/HPPrinter.java b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/HPPrinter.java
@@ -2,8 +2,17 @@
 
 import com.iluwatar.delegation.simple.Printer;
 
+/**
+ * Specialised Implementation of {@link Printer} for a HP Printer, in
+ * this case the message to be printed is appended to "HP Printer : "
+ *
+ * @see Printer
+ */
 public class HPPrinter implements Printer {
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void print(String message) {
         System.out.println("HP Printer : " + message);
