Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJohn Arthorne2012-09-04 12:17:04 -0400
committerJohn Arthorne2012-09-04 12:17:31 -0400
commit3c8a3ced8e97c52fea5e0edb7641b9d94bd6b7bd (patch)
tree7328d53bd4990f59319c700cf64b8f719191d2ab
parent7b190502af5a6386682c36c216ab548e176a93c4 (diff)
downloadrt.equinox.p2-3c8a3ced8e97c52fea5e0edb7641b9d94bd6b7bd.tar.gz
rt.equinox.p2-3c8a3ced8e97c52fea5e0edb7641b9d94bd6b7bd.tar.xz
rt.equinox.p2-3c8a3ced8e97c52fea5e0edb7641b9d94bd6b7bd.zip
Javadoc improvements to metadata APIv20120904-161731
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ICopyright.java5
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnit.java8
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitFragment.java13
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitPatch.java8
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ILicense.java9
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IProvidedCapability.java12
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IRequirement.java9
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointData.java6
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointInstruction.java3
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IUpdateDescriptor.java9
-rw-r--r--bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/MetadataFactory.java14
11 files changed, 82 insertions, 14 deletions
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ICopyright.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ICopyright.java
index d8ad2bd43..7cdf7f654 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ICopyright.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ICopyright.java
@@ -15,6 +15,11 @@ import java.net.URI;
* The <code>ICopyright</code> interface represents a software copyright. A copyright has
* required body text which may be the full text or a summary. An optional location field can be specified
* which links to full text.
+ * <p>
+ * Instances of this class are handle objects and do not necessarily
+ * reflect entities that exist in any particular profile or repository. These handle
+ * objects can be created using {@link MetadataFactory}.
+ * </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnit.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnit.java
index fecc130d5..039f25968 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnit.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnit.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2007, 2010 IBM Corporation and others. All rights reserved. This
+ * Copyright (c) 2007, 2012 IBM Corporation and others. All rights reserved. This
* program and the accompanying materials are made available under the terms of
* the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
@@ -32,10 +32,16 @@ import org.eclipse.equinox.p2.metadata.expression.IMatchExpression;
* weak coupling at work here: installable units never directly depend on each other,
* but instead depend on abstract capabilities that any other installable unit may provide.
* </p>
+ * <p>
+ * Instances of this class are handle objects and do not necessarily
+ * reflect entities that exist in any particular profile or repository. These handle
+ * objects can be created using {@link MetadataFactory}.
+ * </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 2.0
+ * @see MetadataFactory#createInstallableUnit(org.eclipse.equinox.p2.metadata.MetadataFactory.InstallableUnitDescription)
*/
public interface IInstallableUnit extends IVersionedId, Comparable<IInstallableUnit> {
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitFragment.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitFragment.java
index 4268d7e71..4f4636cd4 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitFragment.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitFragment.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2007, 2010 IBM Corporation and others.
+ * Copyright (c) 2007, 2012 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
@@ -13,9 +13,20 @@ package org.eclipse.equinox.p2.metadata;
import java.util.Collection;
/**
+ * Represents a fragment that contributes additional requirements, capabilities,
+ * and other properties to some host installable unit. Installable unit fragments
+ * are not directly installed, but rather they alter the metadata of other installable
+ * units.
+ * <p>
+ * Instances of this class are handle objects and do not necessarily
+ * reflect entities that exist in any particular profile or repository. These handle
+ * objects can be created using {@link MetadataFactory}.
+ * </p>
+ *
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 2.0
+ * @see MetadataFactory#createInstallableUnitFragment(org.eclipse.equinox.p2.metadata.MetadataFactory.InstallableUnitFragmentDescription)
*/
public interface IInstallableUnitFragment extends IInstallableUnit {
public Collection<IRequirement> getHost();
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitPatch.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitPatch.java
index 6e9412e4e..9c09ac3cb 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitPatch.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IInstallableUnitPatch.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2008, 2010 IBM Corporation and others.
+ * Copyright (c) 2008, 2012 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
@@ -15,10 +15,16 @@ import java.util.List;
/**
* An installable unit patch is an installable unit that alters the required capabilities of another
* installable unit.
+ * <p>
+ * Instances of this class are handle objects and do not necessarily
+ * reflect entities that exist in any particular profile or repository. These handle
+ * objects can be created using {@link MetadataFactory}.
+ * </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 2.0
+ * @see MetadataFactory#createInstallableUnitPatch(org.eclipse.equinox.p2.metadata.MetadataFactory.InstallableUnitPatchDescription)
*/
public interface IInstallableUnitPatch extends IInstallableUnit {
/**
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ILicense.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ILicense.java
index 72b0401e5..6f30b086c 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ILicense.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ILicense.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2008, 2010 EclipseSource and others. All rights reserved. This
+* Copyright (c) 2008, 2012 EclipseSource and others. All rights reserved. This
* program and the accompanying materials are made available under the terms of
* the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
@@ -16,6 +16,13 @@ import java.net.URI;
* The <code>ILicense</code> interface represents a software license. A license has required body text
* which may be the full text or an annotation. An optional URL field can be specified
* which links to full text. Licenses can be easily compared using their digests.
+ * Licenses can be added to arbitrary installable units, and will typically be displayed to
+ * end users and require explicit agreement before installation proceeds.
+ * <p>
+ * Instances of this class are handle objects and do not necessarily
+ * reflect entities that exist in any particular profile or repository. These handle
+ * objects can be created using {@link MetadataFactory}.
+ * </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IProvidedCapability.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IProvidedCapability.java
index f8b8cd12c..7848c2dc0 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IProvidedCapability.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IProvidedCapability.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2008, 2010 EclipseSource and others. All rights reserved. This
+* Copyright (c) 2008, 2012 EclipseSource and others. All rights reserved. This
* program and the accompanying materials are made available under the terms of
* the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
@@ -11,11 +11,19 @@
package org.eclipse.equinox.p2.metadata;
/**
- * Describes a capability as exposed or required by an installable unit
+ * Describes a capability that is exposed by an installable unit. These capabilities
+ * can satisfy the dependencies of other installable units, causing the unit
+ * providing the dependency to be installed.
+ * <p>
+ * Instances of this class are handle objects and do not necessarily
+ * reflect entities that exist in any particular profile or repository. These handle
+ * objects can be created using {@link MetadataFactory}.
+ * </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 2.0
+ * @see IRequirement
*/
public interface IProvidedCapability {
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IRequirement.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IRequirement.java
index 5338d47b2..d894e8073 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IRequirement.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IRequirement.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2009, 2010 IBM and others. All rights reserved. This
+* Copyright (c) 2009, 2012 IBM and others. All rights reserved. This
* program and the accompanying materials are made available under the terms of
* the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
@@ -17,10 +17,17 @@ import org.eclipse.equinox.p2.metadata.expression.IMatchExpression;
* it expects to be provided by another {@link IInstallableUnit}. Requirements are
* entirely generic, and are intended to be capable of representing anything that
* an {@link IInstallableUnit} may need either at install time, or at runtime.
+ * <p>
+ * Instances of this class are handle objects and do not necessarily
+ * reflect entities that exist in any particular profile or repository. These handle
+ * objects can be created using {@link MetadataFactory}.
+ * </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 2.0
+ * @see IProvidedCapability
+ * @see MetadataFactory#createRequirement(String, String, VersionRange, String, boolean, boolean, boolean)
*/
public interface IRequirement {
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointData.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointData.java
index 5ce97ab18..4bb61999d 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointData.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointData.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2008, 2010 EclipseSource and others. All rights reserved. This
+* Copyright (c) 2008, 2012 EclipseSource and others. All rights reserved. This
* program and the accompanying materials are made available under the terms of
* the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
@@ -18,7 +18,6 @@ import java.util.Map;
* supporting data needed to perform the phase.
*
* @see MetadataFactory#createTouchpointData(Map)
- *
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 2.0
@@ -27,6 +26,9 @@ public interface ITouchpointData {
/**
* Returns the touchpoint instruction corresponding to the given key.
+ *
+ * @return the touchpoint instruction corresponding to the given key,
+ * or <code>null</code> if no such instruction exists.
*/
public ITouchpointInstruction getInstruction(String instructionKey);
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointInstruction.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointInstruction.java
index c843a85d1..da221d689 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointInstruction.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/ITouchpointInstruction.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2008, 2010 EclipseSource and others. All rights reserved. This
+* Copyright (c) 2008, 2012 EclipseSource and others. All rights reserved. This
* program and the accompanying materials are made available under the terms of
* the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
@@ -44,6 +44,7 @@ package org.eclipse.equinox.p2.metadata;
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 2.0
+ * @see MetadataFactory#createTouchpointInstruction(String, String)
*/
public interface ITouchpointInstruction {
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IUpdateDescriptor.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IUpdateDescriptor.java
index c544741ea..63a0005a8 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IUpdateDescriptor.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/IUpdateDescriptor.java
@@ -25,9 +25,16 @@ import org.eclipse.equinox.p2.metadata.expression.IMatchExpression;
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 2.0
+ * @see MetadataFactory#createUpdateDescriptor(String, VersionRange, int, String)
*/
public interface IUpdateDescriptor {
+ /**
+ * Update severity constant (value 0) indicating a normal severity update.
+ */
public final int NORMAL = 0;
+ /**
+ * Update severity constant (value 1) indicating a high severity update.
+ */
public final int HIGH = 1;
/**
@@ -52,7 +59,7 @@ public interface IUpdateDescriptor {
/**
* The importance of the update descriptor represented as a int.
- * @return The severity.
+ * @return The severity (either {@link #HIGH} or {@link #NORMAL}).
*/
public int getSeverity();
diff --git a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/MetadataFactory.java b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/MetadataFactory.java
index 587a1c77f..12a45a2a0 100644
--- a/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/MetadataFactory.java
+++ b/bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/MetadataFactory.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2007, 2010 IBM Corporation and others.
+ * Copyright (c) 2007, 2012 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
@@ -21,8 +21,7 @@ import org.eclipse.equinox.p2.metadata.expression.*;
/**
* A factory class for instantiating various p2 metadata objects.
- * @noextend
- * @noimplement
+ *
* @since 2.0
*/
public final class MetadataFactory {
@@ -677,6 +676,15 @@ public final class MetadataFactory {
return new UpdateDescriptor(descriptors, severity, description, location);
}
+ /**
+ * Creates a new update descriptor object.
+ * @param id The id of the installable unit that the descriptor provides updates for
+ * @param range The version range that the descriptor provides updates for
+ * @param severity The update severity (either {@link IUpdateDescriptor#NORMAL}
+ * or {@link IUpdateDescriptor#HIGH})
+ * @param description A description of the update
+ * @return A new update descriptor
+ */
public static IUpdateDescriptor createUpdateDescriptor(String id, VersionRange range, int severity, String description) {
return createUpdateDescriptor(id, range, severity, description, null);
}

Back to the top