store descriptions from extension points and extensions in module and plugin descriptors

scm-core/src/main/java/sonia/scm/plugin/ClassElement.java

@@ -58,10 +58,12 @@ public final class ClassElement
    *
    *
    * @param clazz
+   * @param description
    */
-  public ClassElement(Class<?> clazz)
+  public ClassElement(Class<?> clazz, String description)
   {
     this.clazz = clazz;
+    this.description = description;
   }
 
   //~--- methods --------------------------------------------------------------
@@ -89,7 +91,8 @@ public final class ClassElement
 
     final ClassElement other = (ClassElement) obj;
 
-    return Objects.equal(clazz, other.clazz);
+    return Objects.equal(clazz, other.clazz)
+      && Objects.equal(description, other.description);
   }
 
   /**
@@ -101,7 +104,7 @@ public final class ClassElement
   @Override
   public int hashCode()
   {
-    return Objects.hashCode(clazz);
+    return Objects.hashCode(clazz, description);
   }
 
   /**
@@ -116,6 +119,7 @@ public final class ClassElement
     //J-
     return Objects.toStringHelper(this)
                   .add("clazz", clazz)
+                  .add("description", description)
                   .toString();
     //J+
   }
@@ -133,9 +137,23 @@ public final class ClassElement
     return clazz;
   }
 
+  /**
+   * Method description
+   *
+   *
+   * @return
+   */
+  public String getDescription()
+  {
+    return description;
+  }
+
   //~--- fields ---------------------------------------------------------------
 
   /** Field description */
   @XmlElement(name = "class")
   private Class<?> clazz;
+
+  /** Field description */
+  private String description;
 }

scm-core/src/main/java/sonia/scm/plugin/ExtensionPointElement.java

@@ -63,11 +63,14 @@ public final class ExtensionPointElement
    *
    *
    * @param clazz
+   * @param description
    * @param multiple
    */
-  public ExtensionPointElement(Class<?> clazz, boolean multiple)
+  public ExtensionPointElement(Class<?> clazz, String description,
+    boolean multiple)
   {
     this.clazz = clazz;
+    this.description = description;
     this.multiple = multiple;
   }
 
@@ -97,6 +100,7 @@ public final class ExtensionPointElement
     final ExtensionPointElement other = (ExtensionPointElement) obj;
 
     return Objects.equal(clazz, other.clazz)
+      && Objects.equal(description, other.description)
       && Objects.equal(multiple, other.multiple);
   }
 
@@ -109,7 +113,7 @@ public final class ExtensionPointElement
   @Override
   public int hashCode()
   {
-    return Objects.hashCode(clazz, multiple);
+    return Objects.hashCode(clazz, description, multiple);
   }
 
   /**
@@ -124,6 +128,7 @@ public final class ExtensionPointElement
     //J-
     return Objects.toStringHelper(this)
                   .add("class", clazz)
+                  .add("description", description)
                   .add("multiple", multiple)
                   .toString();
     //J+
@@ -142,6 +147,17 @@ public final class ExtensionPointElement
     return clazz;
   }
 
+  /**
+   * Method description
+   *
+   *
+   * @return
+   */
+  public String getDescription()
+  {
+    return description;
+  }
+
   /**
    * Method description
    *
@@ -159,6 +175,9 @@ public final class ExtensionPointElement
   @XmlElement(name = "class")
   private Class<?> clazz;
 
+  /** Field description */
+  private String description;
+
   /** Field description */
   @XmlElement(name = "multi")
   private boolean multiple = true;

scm-core/src/main/java/sonia/scm/plugin/SubscriberElement.java

@@ -34,11 +34,11 @@ package sonia.scm.plugin;
 //~--- non-JDK imports --------------------------------------------------------
 
 import com.google.common.base.Objects;
-import javax.xml.bind.annotation.XmlAccessType;
-import javax.xml.bind.annotation.XmlAccessorType;
 
 //~--- JDK imports ------------------------------------------------------------
 
+import javax.xml.bind.annotation.XmlAccessType;
+import javax.xml.bind.annotation.XmlAccessorType;
 import javax.xml.bind.annotation.XmlElement;
 import javax.xml.bind.annotation.XmlRootElement;
 
@@ -64,11 +64,14 @@ public final class SubscriberElement
    *
    * @param subscriberClass
    * @param eventClass
+   * @param description
    */
-  public SubscriberElement(Class<?> subscriberClass, Class<?> eventClass)
+  public SubscriberElement(Class<?> subscriberClass, Class<?> eventClass,
+    String description)
   {
     this.subscriberClass = subscriberClass;
     this.eventClass = eventClass;
+    this.description = description;
   }
 
   //~--- methods --------------------------------------------------------------
@@ -97,7 +100,8 @@ public final class SubscriberElement
     final SubscriberElement other = (SubscriberElement) obj;
 
     return Objects.equal(eventClass, other.eventClass)
-      && Objects.equal(subscriberClass, other.subscriberClass);
+      && Objects.equal(subscriberClass, other.subscriberClass)
+      && Objects.equal(description, other.description);
   }
 
   /**
@@ -109,7 +113,7 @@ public final class SubscriberElement
   @Override
   public int hashCode()
   {
-    return Objects.hashCode(eventClass, subscriberClass);
+    return Objects.hashCode(eventClass, subscriberClass, description);
   }
 
   /**
@@ -125,12 +129,24 @@ public final class SubscriberElement
     return Objects.toStringHelper(this)
                   .add("eventClass", eventClass)
                   .add("subscriberClass", subscriberClass)
+                  .add("description", description)
                   .toString();
     //J+
   }
 
   //~--- get methods ----------------------------------------------------------
 
+  /**
+   * Method description
+   *
+   *
+   * @return
+   */
+  public String getDescription()
+  {
+    return description;
+  }
+
   /**
    * Method description
    *
@@ -155,6 +171,9 @@ public final class SubscriberElement
 
   //~--- fields ---------------------------------------------------------------
 
+  /** Field description */
+  private String description;
+
   /** Field description */
   @XmlElement(name = "event")
   private Class<?> eventClass;

scm-core/src/test/java/sonia/scm/plugin/ScmModuleTest.java

@@ -77,9 +77,9 @@ public class ScmModuleTest
     assertThat(
       module.getExtensionPoints(), 
       containsInAnyOrder(
-        new ExtensionPointElement(String.class, true), 
-        new ExtensionPointElement(Long.class, true), 
-        new ExtensionPointElement(Integer.class, false)
+        new ExtensionPointElement(String.class, "ext01", true), 
+        new ExtensionPointElement(Long.class, "ext02", true), 
+        new ExtensionPointElement(Integer.class, "ext03", false)
       )
     );
     assertThat(
@@ -92,8 +92,8 @@ public class ScmModuleTest
     assertThat(
       module.getSubscribers(), 
       containsInAnyOrder(
-        new SubscriberElement(Long.class, Integer.class), 
-        new SubscriberElement(Double.class, Float.class)
+        new SubscriberElement(Long.class, Integer.class, "sub01"), 
+        new SubscriberElement(Double.class, Float.class, "sub02")
       )
     );
     assertThat(

scm-core/src/test/resources/sonia/scm/plugin/module.xml

@@ -5,11 +5,13 @@
   <subscriber>
     <class>java.lang.Long</class>
     <event>java.lang.Integer</event>
+    <description>sub01</description>
   </subscriber>
 
   <subscriber>
     <class>java.lang.Double</class>
     <event>java.lang.Float</event>
+    <description>sub02</description>
   </subscriber>
 
   <!-- events -->
@@ -26,15 +28,18 @@
 
   <extension-point>
     <class>java.lang.String</class>
+    <description>ext01</description>
   </extension-point>
 
   <extension-point>
     <class>java.lang.Integer</class>
+    <description>ext03</description>
     <multi>false</multi>
   </extension-point>
 
   <extension-point>
     <class>java.lang.Long</class>
+    <description>ext02</description>
     <multi>true</multi>
   </extension-point>
 

scm-maven-plugins/scm-annotation-processor/src/main/java/sonia/scm/annotation/ClassSetElement.java

@@ -33,6 +33,8 @@ package sonia.scm.annotation;
 
 //~--- non-JDK imports --------------------------------------------------------
 
+import com.google.common.base.Strings;
+
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 
@@ -51,6 +53,9 @@ public class ClassSetElement implements DescriptorElement
   /** Field description */
   private static final String EL_CLASS = "class";
 
+  /** Field description */
+  private static final String EL_DESCRIPTION = "description";
+
   //~--- constructors ---------------------------------------------------------
 
   /**
@@ -87,9 +92,18 @@ public class ClassSetElement implements DescriptorElement
 
       classEl.setTextContent(c.className);
 
+      if (!Strings.isNullOrEmpty(c.description))
+      {
+        Element descriptionEl = doc.createElement(EL_DESCRIPTION);
+
+        descriptionEl.setTextContent(c.description);
+        element.appendChild(descriptionEl);
+      }
+
       for (Entry<String, String> e : c.attributes.entrySet())
       {
         Element attr = doc.createElement(e.getKey());
+
         attr.setTextContent(e.getValue());
         element.appendChild(attr);
       }
@@ -98,7 +112,6 @@ public class ClassSetElement implements DescriptorElement
       root.appendChild(element);
     }
 
-    
   }
 
   //~--- inner classes --------------------------------------------------------
@@ -118,11 +131,14 @@ public class ClassSetElement implements DescriptorElement
      *
      *
      * @param className
+     * @param description
      * @param attributes
      */
-    public ClassWithAttributes(String className, Map<String, String> attributes)
+    public ClassWithAttributes(String className, String description,
+      Map<String, String> attributes)
     {
       this.className = className;
+      this.description = description;
       this.attributes = attributes;
     }
 
@@ -133,6 +149,9 @@ public class ClassSetElement implements DescriptorElement
 
     /** Field description */
     private final String className;
+
+    /** Field description */
+    private final String description;
   }
 
 

scm-maven-plugins/scm-annotation-processor/src/main/java/sonia/scm/annotation/ScmAnnotationProcessor.java

@@ -117,9 +117,15 @@ public final class ScmAnnotationProcessor extends AbstractProcessor
   /** Field description */
   private static final String DESCRIPTOR_PLUGIN = "META-INF/scm/plugin.xml";
 
+  /** Field description */
+  private static final String EL_MODULE = "module";
+
   /** Field description */
   private static final String EMPTY = "";
 
+  /** Field description */
+  private static final String PROPERTY_VALUE = "yes";
+
   /** Field description */
   private static final Set<String> SUBSCRIBE_ANNOTATIONS =
     ImmutableSet.of(Subscribe.class.getName());
@@ -289,7 +295,7 @@ public final class ScmAnnotationProcessor extends AbstractProcessor
       else
       {
         doc = builder.newDocument();
-        doc.appendChild(doc.createElement("module"));
+        doc.appendChild(doc.createElement(EL_MODULE));
       }
     }
     catch (ParserConfigurationException | SAXException | IOException
@@ -344,9 +350,22 @@ public final class ScmAnnotationProcessor extends AbstractProcessor
       if (e.getKind().isClass() || e.getKind().isInterface())
       {
         TypeElement type = (TypeElement) e;
+        String desc = processingEnv.getElementUtils().getDocComment(type);
 
-        classes.add(new ClassWithAttributes(type.getQualifiedName().toString(),
-          getAttributesFromAnnotation(e, annotation)));
+        if (desc != null)
+        {
+          desc = desc.trim();
+        }
+
+        //J-
+        classes.add(
+          new ClassWithAttributes(
+            type.getQualifiedName().toString(),
+            desc,
+            getAttributesFromAnnotation(e, annotation)
+          )
+        );
+        //J+
       }
     }
 
@@ -376,9 +395,23 @@ public final class ScmAnnotationProcessor extends AbstractProcessor
         {
           VariableElement param = params.get(0);
 
+          Element clazz = el.getEnclosingElement();
+          String desc = processingEnv.getElementUtils().getDocComment(clazz);
+
+          if (desc != null)
+          {
+            desc = desc.trim();
+          }
+
+          //J-
           descriptorElements.add(
             new SubscriberElement(
-              el.getEnclosingElement().toString(), param.asType().toString()));
+              clazz.toString(), 
+              param.asType().toString(),
+              desc
+            )
+          );
+          //J+
         }
       }
     }
@@ -438,7 +471,7 @@ public final class ScmAnnotationProcessor extends AbstractProcessor
       Transformer transformer =
         TransformerFactory.newInstance().newTransformer();
 
-      transformer.setOutputProperty(OutputKeys.INDENT, "yes");
+      transformer.setOutputProperty(OutputKeys.INDENT, PROPERTY_VALUE);
       transformer.transform(new DOMSource(doc), new StreamResult(writer));
     }
     catch (IOException | IllegalArgumentException | TransformerException ex)

scm-maven-plugins/scm-annotation-processor/src/main/java/sonia/scm/annotation/SubscriberElement.java

@@ -33,6 +33,8 @@ package sonia.scm.annotation;
 
 //~--- non-JDK imports --------------------------------------------------------
 
+import com.google.common.base.Strings;
+
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 
@@ -46,6 +48,9 @@ public class SubscriberElement implements DescriptorElement
   /** Field description */
   private static final String EL_CLASS = "class";
 
+  /** Field description */
+  private static final String EL_DESCRIPTION = "description";
+
   /** Field description */
   private static final String EL_EVENT = "event";
 
@@ -60,11 +65,14 @@ public class SubscriberElement implements DescriptorElement
    *
    * @param subscriberType
    * @param eventType
+   * @param description
    */
-  public SubscriberElement(String subscriberType, String eventType)
+  public SubscriberElement(String subscriberType, String eventType,
+    String description)
   {
     this.subscriberType = subscriberType;
     this.eventType = eventType;
+    this.description = description;
   }
 
   //~--- methods --------------------------------------------------------------
@@ -89,11 +97,23 @@ public class SubscriberElement implements DescriptorElement
 
     eventEl.setTextContent(eventType);
     subscriberEl.appendChild(eventEl);
+
+    if (!Strings.isNullOrEmpty(description))
+    {
+      Element descriptionEl = doc.createElement(EL_DESCRIPTION);
+
+      descriptionEl.setTextContent(description);
+      subscriberEl.appendChild(descriptionEl);
+    }
+
     root.appendChild(subscriberEl);
   }
 
   //~--- fields ---------------------------------------------------------------
 
+  /** Field description */
+  private final String description;
+
   /** Field description */
   private final String eventType;