547289 Provide javadoc for org.eclipse.passage.lic.api package

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/AccessEvents.java

@@ -18,6 +18,9 @@
 
 import org.eclipse.passage.lic.api.conditions.LicensingCondition;
 
+/**
+ * @since 0.4.0
+ */
 public final class AccessEvents {
 
 	private AccessEvents() {

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/AccessManager.java

@@ -21,6 +21,7 @@
 /**
  * The main entry point to the licensing
  *
+ * @since 0.4.0
  */
 public interface AccessManager {
 

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/FeaturePermission.java

@@ -18,17 +18,37 @@
 import org.eclipse.passage.lic.api.conditions.LicensingCondition;
 
 /**
- * Permission to use the component of given name and version range obtained from
- * {@link PermissionEmitter} as a result of evaluation for
- * {@link LicensingCondition}
+ * Permission expresses runtime state of a satisfied {@link LicensingCondition}:
+ * all terms that {@link LicensingCondition} establishes are fulfilled and the
+ * permission to use the feature of given name and version range is issues by
+ * {@link PermissionEmitter}.
+ * <p>
+ * In other words, {@link PermissionEmitter} <i>evaluates</i> a {@link LicensingCondition} and <i>emits or not</i>
+ * corresponding {@link FeaturePermission}.
+ *
+ * @since 0.4.0
  */
 public interface FeaturePermission {
 
 	LicensingConfiguration getLicensingConfiguration();
 
+    /**
+     * The original {@code LicensingCondition} for which this {@link FeaturePermission} was emitted.
+     */
 	LicensingCondition getLicensingCondition();
 
+    /**
+     * In general case a {@link FeaturePermission} is time-limited.
+     * {@code LeaseDate} is timestamp of the permission emission.
+     *
+     * @see #getExpireDate()
+     */
 	Date getLeaseDate();
 
+    /**
+     * The date of the permission expiration. It is no longer valid after this date.
+     *
+     * @see #getLeaseDate()
+     */
 	Date getExpireDate();
 }

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/LicensingRequest.java

@@ -18,9 +18,8 @@
 
 /**
  * Collects the data required to issue the license
- * 
- * @since 0.5.0
  *
+ * @since 0.5.0
  */
 public interface LicensingRequest {
 

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/PermissionEmitter.java

@@ -17,12 +17,20 @@
 import org.eclipse.passage.lic.api.conditions.LicensingCondition;
 
 /**
- * Evaluates the collection of {@link LicensingCondition} to emit a collection
- * of {@link FeaturePermission}
+ * Interface of a service responsible for {@link LicensingCondition}s evaluation against the current program runtime.
+ * As a result of evaluation, for a {@link LicensingCondition} a {@code FeaturePermission} can be emitted,
+ * in case all the {@link LicensingCondition}'s terms are met at the current program runtime.
  *
+ * @see LicensingCondition
+ * @see FeaturePermission
+ * @since 0.4.0
  */
 public interface PermissionEmitter {
-
+	/**
+	 * Evaluates the collection of {@link LicensingCondition} to emit a collection
+	 * of {@link FeaturePermission}
+	 *
+	 */
 	Iterable<FeaturePermission> emitPermissions(LicensingConfiguration configuration,
 			Iterable<LicensingCondition> conditions) throws LicensingException;
 

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/PermissionEmitterRegistry.java

@@ -12,6 +12,11 @@
  *******************************************************************************/
 package org.eclipse.passage.lic.api.access;
 
+/**
+ * Takes care of all {@link PermissionEmitter} services registered at runtime.
+ *
+ * @since 0.4.0
+ */
 public interface PermissionEmitterRegistry {
 
 	String getDefaultConditionType();

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/PermissionExaminer.java

@@ -18,12 +18,31 @@
 import org.eclipse.passage.lic.api.restrictions.RestrictionVerdict;
 
 /**
- * Examines how {@link FeaturePermission}(s) cover the
- * {@link LicensingRequirement}(s) and produce {@link RestrictionVerdict}(s) to
- * be consumed by {@link RestrictionExecutor}(s)
+ * The contract for a service responsible for examining set of {@link FeaturePermission}s
+ * (runtime-evaluated {@code LicensingCondition}s)
+ * against all {@link LicensingRequirement}s for the same set of features.
+ * Examining reports which {@link LicensingRequirement}s are left unsatisfied.
+ *
+ * @see LicensingRequirement
+ * @see PermissionEmitter
+ * @see FeaturePermission
+ * @see RestrictionVerdict
+ * @since 0.4.0
  */
 public interface PermissionExaminer {
 
+	/**
+	 * Examines how {@link FeaturePermission}s cover the
+	 * {@link LicensingRequirement}s and produce {@link RestrictionVerdict}s to
+	 * be consumed by {@link RestrictionExecutor}s.
+	 * Each {@link RestrictionVerdict} describes uncovered {@link LicensingRequirement}
+	 *
+	 * @param configuration overall configuration
+	 * @param requirements  program licensing requirements to be covered by the {@code permissions}
+	 * @param permissions   feature permissions collected for the appropriate set of features
+	 * @return not null iterable structure of {@link RestrictionVerdict}s begotten by all the {@code requirements} unsatisfied
+	 * by the given {@code permissions}
+	 */
 	Iterable<RestrictionVerdict> examine(LicensingConfiguration configuration,
 			Iterable<LicensingRequirement> requirements, Iterable<FeaturePermission> permissions);
 

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/PermissionTransport.java

@@ -18,6 +18,8 @@
 
 /**
  * Transport interface for {@link FeaturePermission}(s)
+ *
+ * @since 0.4.0
  */
 public interface PermissionTransport {