Sonar API - Try to improve documentation of notifications

4 files changed, 88 insertions, 12 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/Notification.java b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/Notification.java
index de1b5cd9075..c69cc777d3f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/Notification.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/Notification.java
@@ -19,35 +19,69 @@
  */
 package org.sonar.api.notifications;
 
-import com.google.common.collect.Maps;
+import java.io.Serializable;
+import java.util.HashMap;
+
 import org.apache.commons.lang.builder.ReflectionToStringBuilder;
 import org.apache.commons.lang.builder.ToStringStyle;
 
-import java.io.Serializable;
-import java.util.HashMap;
+import com.google.common.collect.Maps;
 
 /**
+ * <p>
+ * This class represents a notification that will be delivered to users. This is a general concept and it has no
+ * knowledge of the possible ways to be delivered (see {@link NotificationChannel}) or of the users who should
+ * receive it (see {@link NotificationDispatcher}).
+ * </p> 
+ * 
  * @since 2.10
  */
 public class Notification implements Serializable {
 
   private String type;
 
-  private HashMap<String, String> fields = Maps.newHashMap(); // NOSONAR false-positive due to serialization : usage of HashMap instead of Map
+  private HashMap<String, String> fields = Maps.newHashMap(); // NOSONAR false-positive due to serialization : usage of HashMap instead of
+                                                              // Map
 
+  /**
+   * <p>
+   * Create a new {@link Notification} of the given type.
+   * </p>
+   * Example: type = "new-violations"
+   * 
+   * @param type the type of notification
+   */
   public Notification(String type) {
     this.type = type;
   }
 
+  /**
+   * Returns the type of the notification
+   * 
+   * @return the type
+   */
   public String getType() {
     return type;
   }
 
+  /**
+   * Adds a field (kind of property) to the notification
+   * 
+   * @param field the name of the field (= the key)
+   * @param value the value of the field
+   * @return the notification itself
+   */
   public Notification setFieldValue(String field, String value) {
     fields.put(field, value);
     return this;
   }
 
+  /**
+   * Returns the value of a field.
+   * 
+   * @param field the field
+   * @return the value of the field
+   */
   public String getFieldValue(String field) {
     return fields.get(field);
   }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationChannel.java b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationChannel.java
index cef007a3f65..a187218b087 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationChannel.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationChannel.java
@@ -22,7 +22,9 @@ package org.sonar.api.notifications;
 import org.sonar.api.ServerExtension;
 
 /**
- * Provides logic to deliver notification.
+ * <p>
+ * Plugins should extend this class to provide implementation on a specific way to deliver notifications.
+ * </p>
  * For example:
  * <ul>
  * <li>email - sends email as soon as possible</li>
@@ -35,13 +37,21 @@ import org.sonar.api.ServerExtension;
 public abstract class NotificationChannel implements ServerExtension {
 
   /**
-   * @return unique key of this channel
+   * Returns the unique key of this channel. 
+   * 
+   * @return the key
    */
   public String getKey() {
     return getClass().getSimpleName();
   }
 
-  public abstract void deliver(Notification notification, String username);
+  /**
+   * Implements the delivery of the given notification to the given user.
+   * 
+   * @param notification the notification to deliver
+   * @param userlogin the login of the user who should receive the notification
+   */
+  public abstract void deliver(Notification notification, String userlogin);
 
   @Override
   public String toString() {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationDispatcher.java b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationDispatcher.java
index f905fd5ef52..0516215729a 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationDispatcher.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationDispatcher.java
@@ -22,8 +22,10 @@ package org.sonar.api.notifications;
 import org.sonar.api.ServerExtension;
 
 /**
- * Provides logic to determine which users are interested in receiving notification.
- * Has no knowledge about the way of delivery.
+ * <p>
+ * Plugins should extend this class to provide logic to determine which users are interested in receiving notifications.
+ * It has no knowledge about the way of delivery.
+ * </p>
  * For example:
  * <ul>
  * <li>notify me when someone comments on review created by me</li>
@@ -36,19 +38,36 @@ import org.sonar.api.ServerExtension;
  */
 public abstract class NotificationDispatcher implements ServerExtension {
 
+  /**
+   * Additional information related to the notification, which will be used
+   * to know who should receive the notification.
+   */
   public interface Context {
-    void addUser(String username);
+    /**
+     * Adds a user that will be notified.
+     * 
+     * @param userLogin the user login
+     */
+    void addUser(String userLogin);
   }
 
   /**
-   * @return unique key of this dispatcher
+   * Returns the unique key of this dispatcher. 
+   * 
+   * @return the key
    */
   public String getKey() {
     return getClass().getSimpleName();
   }
 
   /**
-   * @return recipients
+   * <p>
+   * Implements the logic that defines which users will receive the notification.
+   * </p>
+   * The purpose of this method is to populate the context object with users, based on the type of notification and the content of the notification.
+   * 
+   * @param notification the notification that will be sent
+   * @param the context linked to this notification
    */
   public abstract void dispatch(Notification notification, Context context);
 
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationManager.java b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationManager.java
index 834c990fdb8..10879bf19de 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationManager.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/notifications/NotificationManager.java
@@ -23,10 +23,23 @@ import org.sonar.api.BatchComponent;
 import org.sonar.api.ServerComponent;
 
 /**
+ * <p>
+ * The notification manager receives notifications and is in charge of storing them so that they are processed by the notification service.
+ * </p>
+ * <p>
+ * Pico provides an instance of this class, and plugins just need to create notifications and pass them to this manager with 
+ * the {@link NotificationManager#scheduleForSending(Notification)} method.
+ * </p>
+ * 
  * @since 2.10
  */
 public interface NotificationManager extends ServerComponent, BatchComponent {
 
+  /**
+   * Receives a notification and stores it so that it is processed by the notification service.
+   * 
+   * @param notification the notification.
+   */
   void scheduleForSending(Notification notification);
 
 }