diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/Component.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/Component.java
index 496dd7d..9ca5ee8 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/Component.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/Component.java
@@ -19,7 +19,7 @@
 import javax.jbi.management.ComponentLifeCycleMBean;
 
 /**
- * Represents a JBI component lifecycle.
+ * Represents a JBI component.
  */
 public interface Component extends ComponentLifeCycleMBean {
 
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ClassPath.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ClassPath.java
index 567b836..0d9f51f 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ClassPath.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ClassPath.java
@@ -20,7 +20,7 @@
 import java.util.List;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>jbi:classpath</code> complex type.
  */
 public class ClassPath {
     
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ComponentDesc.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ComponentDesc.java
index 52ee503..7a8f8d0 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ComponentDesc.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ComponentDesc.java
@@ -19,7 +19,7 @@
 import org.apache.servicemix.jbi.deployer.descriptor.ClassPath;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:component&gt;</code> element.
  */
 public class ComponentDesc {
     private String type;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Connection.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Connection.java
index d39d964..8fe38bd 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Connection.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Connection.java
@@ -17,7 +17,7 @@
 package org.apache.servicemix.jbi.deployer.descriptor;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:connection&gt;</code> element.
  */
 public class Connection {
     private Consumer consumer;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Connections.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Connections.java
index 7dd091e..b6c6aa2 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Connections.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Connections.java
@@ -19,11 +19,11 @@
 import org.apache.servicemix.jbi.deployer.descriptor.Connection;
 
 /**
- * Inner class used to handle the grouping of connections
- * 
+ * The <code>&lt;jbi:connections&gt;</code> element.
  */
 public class Connections {
-	private Connection[] connections;
+
+    private Connection[] connections;
 
 	public Connection[] getConnections() {
 		return connections;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Consumer.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Consumer.java
index bb48976..ba08045 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Consumer.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Consumer.java
@@ -19,9 +19,7 @@
 import javax.xml.namespace.QName;
 
 /**
- * Specifies either an interface name or a service and endpoint name.
- *
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:consumer&gt;</code> element.
  */
 public class Consumer {
     private QName interfaceName;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Consumes.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Consumes.java
index 8327173..cfab485 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Consumes.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Consumes.java
@@ -19,9 +19,7 @@
 import javax.xml.namespace.QName;
 
 /**
- * Specifies either an interface name or a service and endpoint name.
- *
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:consumes&gt;</code> element.
  */
 public class Consumes {
     private QName interfaceName;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Descriptor.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Descriptor.java
index 124eeb5..a3e04ea 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Descriptor.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Descriptor.java
@@ -16,12 +16,11 @@
  */
 package org.apache.servicemix.jbi.deployer.descriptor;
 
-import org.apache.servicemix.jbi.deployer.descriptor.ComponentDesc;
-
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:jbi&gt;</code> element.
  */
 public class Descriptor {
+
     private double version;
     private ComponentDesc component;
     private SharedLibraryDesc sharedLibrary;
@@ -69,94 +68,3 @@
     }
 }
 
-/*
-default namespace this = "http://java.sun.com/xml/ns/jbi"
-start =
-  element jbi {
-    attribute version { xsd:decimal },
-    ( component | shared-library | service-assembly | services)
-  }
-component =
-  element component {
-    attribute type { "service-engine" | "binding-component" },
-    attribute component-class-loader-delegation { "parent-first" | "self-first" }?,
-    attribute bootstrap-class-loader-delegation { "parent-first" | "self-first" }?,
-    identification,
-    element component-class-name { attribute description { text }?, text },
-    element component-class-path { class-path },
-    element bootstrap-class-name { text },
-    element bootstrap-class-path { class-path },
-    shared-library-list*,
-    element* -this:* { text }*
-  }
-shared-library =
-  element shared-library {
-    attribute class-loader-delegation { "parent-first" | "self-first" }?,
-    attribute version { text }?,
-    identification,
-    element shared-library-class-path { class-path }
-  }
-shared-library-list =
-  element shared-library {
-    attribute version { text }?,
-    text
-  }
-service-assembly =
-  element service-assembly {
-    identification,
-    service-unit*,
-    connections?,
-    element* -this:* { text }*
-  }
-service-unit =
-  element service-unit {
-    identification,
-    element target {
-      element artifacts-zip { text },
-      element component-name { xsd:NCName }
-    },
-    element* -this:* { text }*
-  }
-identification =
-  element identification {
-    element name { xsd:NCName },
-    element description { text },
-    element* -this:* { text }*
- }
-class-path =
-  (element path-element { text })+
-services =
-  element services {
-    attribute binding-component { xsd:boolean },
-    provides*,
-    consumes*,
-    element* -this:* { text }*
-  }
-connections =
-  element connections {
-    element connection {
-      element consumer {
-        ( attribute interface-name { xsd:QName } |
-          (attribute service-name { xsd:QName }, attribute endpoint-name { text })
-        )
-      },
-      element provider {
-        attribute service-name { xsd:QName }, attribute endpoint-name { text }
-      }
-    }*,
-    element* -this:* { text }*
-  }
-provides =
-  element provides {
-    attribute interface-name { xsd:QName },
-    attribute service-name {xsd:QName }, attribute endpoint-name { text },
-    element* -this:* { text }*
-  }
-consumes =
-  element consumes {
-    attribute interface-name { xsd:QName },
-    ( attribute service-name {xsd:QName }, attribute endpoint-name { text },
-      attribute link-type { "standard" | "hard" | "soft" }? )?,
-    element* -this:* { text }*
-  }
-*/
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/DescriptorFactory.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/DescriptorFactory.java
index 6ad5209..d595401 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/DescriptorFactory.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/DescriptorFactory.java
@@ -46,7 +46,7 @@
 import org.xml.sax.SAXParseException;
 
 /**
- * @version $Revision: 359151 $
+ * Factory to read a JBI descriptor from a file, url or stream.
  */
 public class DescriptorFactory {
 
@@ -55,10 +55,13 @@
      */
     private static final String XSD_SCHEMA_LANGUAGE = "http://www.w3.org/2001/XMLSchema";
 
+    /**
+     * The location of the JBI descriptor in a JBI artifact.
+     */
     public static final String DESCRIPTOR_FILE = "META-INF/jbi.xml";
 
     /**
-     * Build a jbi descriptor from a file archive
+     * Build a jbi descriptor from a file archive.
      * 
      * @param descriptorFile
      *            path to the jbi descriptor, or to the root directory
@@ -113,9 +116,11 @@
     }
 
     /**
-     * Build a jbi descriptor from the specified binary data
+     * Build a jbi descriptor from the specified binary data.
+     * The descriptor is validated against the schema, but no
+     * semantic validation is performed.
      * 
-     * @param bytes
+     * @param bytes hold the content of the JBI descriptor xml document
      * @return the Descriptor object
      */
     public static Descriptor buildDescriptor(final byte[] bytes) {
@@ -338,7 +343,7 @@
     }
 
     /**
-     * Check validity of the JBI descriptor
+     * Check validity of the JBI descriptor.
      * 
      * @param descriptor
      *            the descriptor to check
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Identification.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Identification.java
index a4c77b0..98a8cf1 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Identification.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Identification.java
@@ -17,7 +17,7 @@
 package org.apache.servicemix.jbi.deployer.descriptor;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:identification&gt;</code> element.
  */
 public class Identification {
     private String name;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/InstallationDescriptorExtension.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/InstallationDescriptorExtension.java
index 0f4ce77..d1a6c81 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/InstallationDescriptorExtension.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/InstallationDescriptorExtension.java
@@ -20,8 +20,6 @@
 
 /**
  * A POJO used to hold the descriptor extension.
- *
- * @version $Revision: 426415 $
  */
 public class InstallationDescriptorExtension {
     DocumentFragment descriptorExtension;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Provider.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Provider.java
index 9a33417..05b6bd2 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Provider.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Provider.java
@@ -19,7 +19,7 @@
 import javax.xml.namespace.QName;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:provider&gt;</code> element.
  */
 public class Provider {
     private QName serviceName;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Provides.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Provides.java
index ce8be0b..b53145b 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Provides.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Provides.java
@@ -19,7 +19,7 @@
 import javax.xml.namespace.QName;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:provides&gt;</code> element.
  */
 public class Provides {
     private QName serviceName;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ServiceAssemblyDesc.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ServiceAssemblyDesc.java
index 3d24744..6432777 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ServiceAssemblyDesc.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ServiceAssemblyDesc.java
@@ -17,7 +17,7 @@
 package org.apache.servicemix.jbi.deployer.descriptor;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:service-assembly&gt;</code> element.
  */
 public class ServiceAssemblyDesc {
 
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ServiceUnitDesc.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ServiceUnitDesc.java
index 73a48be..5d2faba 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ServiceUnitDesc.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/ServiceUnitDesc.java
@@ -17,7 +17,7 @@
 package org.apache.servicemix.jbi.deployer.descriptor;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:service-unit&gt;</code> element.
  */
 public class ServiceUnitDesc {
     private Identification identification;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Services.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Services.java
index 64e1ecb..f9d0771 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Services.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Services.java
@@ -17,7 +17,7 @@
 package org.apache.servicemix.jbi.deployer.descriptor;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:services&gt;</code> element.
  */
 public class Services {
     private boolean bindingComponent;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/SharedLibraryDesc.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/SharedLibraryDesc.java
index 328bd5a..623e68f 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/SharedLibraryDesc.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/SharedLibraryDesc.java
@@ -17,7 +17,7 @@
 package org.apache.servicemix.jbi.deployer.descriptor;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:shared-library&gt;</code> element.
  */
 public class SharedLibraryDesc {
     private String classLoaderDelegation = "parent-first";
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/SharedLibraryList.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/SharedLibraryList.java
index b22c7c2..a1db59f 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/SharedLibraryList.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/SharedLibraryList.java
@@ -17,7 +17,7 @@
 package org.apache.servicemix.jbi.deployer.descriptor;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>jbi:shared-library-list</code> complex type.
  */
 public class SharedLibraryList {
     private String version;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Target.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Target.java
index 75adce4..547f2fd 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Target.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/Target.java
@@ -17,7 +17,7 @@
 package org.apache.servicemix.jbi.deployer.descriptor;
 
 /**
- * @version $Revision: 426415 $
+ * The <code>&lt;jbi:target&gt;</code> element.
  */
 public class Target {
     private String artifactsZip;
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/package.html b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/package.html
new file mode 100644
index 0000000..e468b23
--- /dev/null
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/descriptor/package.html
@@ -0,0 +1,118 @@
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<html>
+<head>
+</head>
+<body>
+
+JBI descriptor POJOs based model.
+
+Relax NG Schema for JBI descriptor:
+<pre>
+    default namespace this = "http://java.sun.com/xml/ns/jbi"
+    start =
+      element jbi {
+        attribute version { xsd:decimal },
+        ( component | shared-library | service-assembly | services)
+      }
+    component =
+      element component {
+        attribute type { "service-engine" | "binding-component" },
+        attribute component-class-loader-delegation { "parent-first" | "self-first" }?,
+        attribute bootstrap-class-loader-delegation { "parent-first" | "self-first" }?,
+        identification,
+        element component-class-name { attribute description { text }?, text },
+        element component-class-path { class-path },
+        element bootstrap-class-name { text },
+        element bootstrap-class-path { class-path },
+        shared-library-list*,
+        element* -this:* { text }*
+      }
+    shared-library =
+      element shared-library {
+        attribute class-loader-delegation { "parent-first" | "self-first" }?,
+        attribute version { text }?,
+        identification,
+        element shared-library-class-path { class-path }
+      }
+    shared-library-list =
+      element shared-library {
+        attribute version { text }?,
+        text
+      }
+    service-assembly =
+      element service-assembly {
+        identification,
+        service-unit*,
+        connections?,
+        element* -this:* { text }*
+      }
+    service-unit =
+      element service-unit {
+        identification,
+        element target {
+          element artifacts-zip { text },
+          element component-name { xsd:NCName }
+        },
+        element* -this:* { text }*
+      }
+    identification =
+      element identification {
+        element name { xsd:NCName },
+        element description { text },
+        element* -this:* { text }*
+     }
+    class-path =
+      (element path-element { text })+
+    services =
+      element services {
+        attribute binding-component { xsd:boolean },
+        provides*,
+        consumes*,
+        element* -this:* { text }*
+      }
+    connections =
+      element connections {
+        element connection {
+          element consumer {
+            ( attribute interface-name { xsd:QName } |
+              (attribute service-name { xsd:QName }, attribute endpoint-name { text })
+            )
+          },
+          element provider {
+            attribute service-name { xsd:QName }, attribute endpoint-name { text }
+          }
+        }*,
+        element* -this:* { text }*
+      }
+    provides =
+      element provides {
+        attribute interface-name { xsd:QName },
+        attribute service-name {xsd:QName }, attribute endpoint-name { text },
+        element* -this:* { text }*
+      }
+    consumes =
+      element consumes {
+        attribute interface-name { xsd:QName },
+        ( attribute service-name {xsd:QName }, attribute endpoint-name { text },
+          attribute link-type { "standard" | "hard" | "soft" }? )?,
+        element* -this:* { text }*
+      }
+</pre>
+
+</body>
+</html>
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/Connection.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/Connection.java
index a8167bd..e0f1aa6 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/Connection.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/Connection.java
@@ -29,7 +29,10 @@
 import org.apache.commons.logging.LogFactory;
 import org.apache.servicemix.jbi.deployer.impl.FileUtil;
 
-
+/**
+ * A URL connection to handle the JBI to OSGi transformation
+ * using a URL.
+ */
 public class Connection extends URLConnection {
 	
 	private static Log logger = LogFactory.getLog(Connection.class);
@@ -42,15 +45,22 @@
 	}
 
 
-	@Override
-	public void connect() throws IOException {
-		
+    /**
+     * Connect method.  Nothing to do in our case.
+     */
+    @Override
+	public void connect() {
 	}
-	
-	@Override
+
+    /**
+     * Retrieve an InputStream on the OSGi bundle.
+     * 
+     * @return an InputStream used to read the transformation output.
+     * @throws IOException if an error occurs when transforming the JBI artifact.
+     */
+    @Override
 	public InputStream getInputStream() throws IOException {
 		try {
-			connect();
 			InputStream targetInputStream = urlHandler.getJbiArtifactURL().openConnection().getInputStream();
 			File jbiZipFile = File.createTempFile("jbi", ".zip");
 			FileOutputStream jbiZip = new FileOutputStream(jbiZipFile);
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/JBIDeploymentListener.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/JBIDeploymentListener.java
index 4ef4832..6987b23 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/JBIDeploymentListener.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/JBIDeploymentListener.java
@@ -24,14 +24,27 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.apache.servicemix.jbi.deployer.descriptor.DescriptorFactory;
 import org.apache.servicemix.kernel.filemonitor.DeploymentListener;
 
-
+/**
+ * A JBI DeploymentListener which transforms plain JBI artifacts to OSGi bundles.
+ * The deployer will recognize zip and jar files containing a JBI descriptor and
+ * without any OSGi manifest entries.
+ */
 public class JBIDeploymentListener implements DeploymentListener {
 	
 	private static final Log Logger = LogFactory.getLog(JBIDeploymentListener.class);
-	
-	public boolean canHandle(File artifact) {
+
+    /**
+     * Check if the file is a recognized JBI artifact that needs to be
+     * processed.
+     *
+     * @param artifact the file to check
+     * @return <code>true</code> is the file is a JBI artifact that
+     *         should be transformed into an OSGi bundle.
+     */
+    public boolean canHandle(File artifact) {
 		try {
             // Accept jars and zips
             if (!artifact.getName().endsWith(".zip") &&
@@ -39,7 +52,7 @@
                 return false;
             }
 			JarFile jar = new JarFile(artifact);
-			JarEntry entry = jar.getJarEntry("META-INF/jbi.xml");
+			JarEntry entry = jar.getJarEntry(DescriptorFactory.DESCRIPTOR_FILE);
             // Only handle JBI artifacts
             if (entry == null) {
 				return false;
@@ -57,8 +70,16 @@
 		}
 	}
 
-	
-	public File handle(File artifact, File tmpDir) {
+
+    /**
+     * Transform the file, which is a JBI artifact, into an OSGi bundle.
+     *
+     * @param artifact the file to transform.
+     * @param tmpDir the location where the file should be stored.
+     * @return the location of the transformed OSGi bundle, or <code>null</code>
+     *         if the transformation could not take place.
+     */
+    public File handle(File artifact, File tmpDir) {
 		try{
 			String bundleName = artifact.getName().substring(0, artifact.getName().length() -4 ) + ".jar";
 			File destFile = new File(tmpDir, bundleName);
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/Transformer.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/Transformer.java
index d210415..dcbbe95 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/Transformer.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/Transformer.java
@@ -31,11 +31,30 @@
 import org.apache.servicemix.jbi.deployer.impl.FileUtil;
 
 /**
- * Helper class to transform JBI artifacts into OSGi bundles
+ * Helper class to transform JBI artifacts into OSGi bundles.
  */
 public class Transformer {
 
-    public static void transformToOSGiBundle(File jbiArtifact, File jbiBundle) throws Exception {
+    /**
+     * Prevent instanciation.
+     */
+    private Transformer() {
+    }
+
+    /**
+     * Create an OSGi bundle from the JBI artifact.
+     * The process creates the following OSGi manifest entries:
+     * <ul>
+     *   <li><b><code>Bundle-SymbolicName</code></b>: the name of the JBI artifact</li>
+     *   <li><b><code>Bundle-Version</code></b>: retrieved from the <code>Implementation-Version</code> manifest entry</li>
+     *   <li><b><code>DynamicImport-Package</code></b>: javax.*,org.xml.*,org.w3c.*</li>
+     * </ul>
+     *
+     * @param jbiArtifact the input JBI artifact.
+     * @param osgiBundle the output OSGi bundle.
+     * @throws Exception if an error occurs during the transformation process.
+     */
+    public static void transformToOSGiBundle(File jbiArtifact, File osgiBundle) throws Exception {
     	JarFile jar = new JarFile(jbiArtifact);
         Manifest m = jar.getManifest();
         if (m == null) {
@@ -62,7 +81,7 @@
         m.getMainAttributes().putValue("DynamicImport-Package", "javax.*,org.xml.*,org.w3c.*");
 
 		JarInputStream jis = new JarInputStream(new FileInputStream(jbiArtifact));
-		JarOutputStream jos = new JarOutputStream(new FileOutputStream(jbiBundle), m);
+		JarOutputStream jos = new JarOutputStream(new FileOutputStream(osgiBundle), m);
 
 		JarEntry entry = jis.getNextJarEntry();
 		while (entry != null) {
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/URLHandler.java b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/URLHandler.java
index aa7a71b..2c38806 100644
--- a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/URLHandler.java
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/URLHandler.java
@@ -26,10 +26,9 @@
 import org.apache.commons.logging.LogFactory;
 import org.osgi.service.url.AbstractURLStreamHandlerService;
 
-
 /**
  * A URL handler that will transform a JBI artifact to an OSGi bundle
- * on the fly.
+ * on the fly.  Needs to be registered in the OSGi registry.
  */
 public class URLHandler extends AbstractURLStreamHandlerService {
 	
@@ -38,8 +37,15 @@
 	private static String SYNTAX = "jbi: jbi-jar-uri";
 	
 	private URL jbiArtifactURL;
-	
-	@Override
+
+    /**
+     * Open the connection for the given URL.
+     *
+     * @param url the url from which to open a connection.
+     * @return a connection on the specified URL.
+     * @throws IOException if an error occurs or if the URL is malformed.
+     */
+    @Override
 	public URLConnection openConnection(URL url) throws IOException {
 		if (url.getPath() == null || url.getPath().trim().length() == 0) {
 			throw new MalformedURLException ("Path can not be null or empty. Syntax: " + SYNTAX );
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/package.html b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/package.html
new file mode 100644
index 0000000..9dddf67
--- /dev/null
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/handler/package.html
@@ -0,0 +1,25 @@
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<html>
+<head>
+</head>
+<body>
+
+Transformation of JBI artifacts to OSGi bundles.
+
+</body>
+</html>
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/impl/package.html b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/impl/package.html
new file mode 100644
index 0000000..02923c7
--- /dev/null
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/impl/package.html
@@ -0,0 +1,25 @@
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<html>
+<head>
+</head>
+<body>
+
+OSGi deployer implementation for JBI artifacts.
+
+</body>
+</html>
diff --git a/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/package.html b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/package.html
new file mode 100644
index 0000000..3ad64cd
--- /dev/null
+++ b/jbi/deployer/src/main/java/org/apache/servicemix/jbi/deployer/package.html
@@ -0,0 +1,25 @@
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<html>
+<head>
+</head>
+<body>
+
+Contains interfaces defining Services associated to JBI artifacts.
+
+</body>
+</html>