From 1e7f338b8dfbb934c17cbadf2222692bcf3d1f92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20L=C3=A4ubrich?= Date: Sat, 13 Jan 2024 07:34:04 +0100 Subject: [PATCH] Fix more javadoc --- .../internal/StructuredTextDelimsEsc.java | 2 +- .../bidi/internal/StructuredTextImpl.java | 7 +- .../org/eclipse/core/text/StringMatcher.java | 5 +- .../equinox/events/MemoryEventConstants.java | 4 +- .../osgi/framework/util/SecureAction.java | 10 +- .../osgi/storage/bundlefile/BundleFile.java | 7 +- .../storage/bundlefile/BundleFileWrapper.java | 11 +- .../osgi/storage/url/reference/Handler.java | 17 ++- .../org/eclipse/equinox/log/LogFilter.java | 9 +- .../report/resolution/ResolutionReport.java | 136 +++++++++--------- 10 files changed, 116 insertions(+), 92 deletions(-) diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/StructuredTextDelimsEsc.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/StructuredTextDelimsEsc.java index 70a4806b18e..91651279673 100644 --- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/StructuredTextDelimsEsc.java +++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/StructuredTextDelimsEsc.java @@ -24,13 +24,13 @@ *

* This is similar to {@link StructuredTextDelims} except that delimiters can be * escaped using the backslash character. + *

* - *

*/ public abstract class StructuredTextDelimsEsc extends StructuredTextDelims { diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/StructuredTextImpl.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/StructuredTextImpl.java index 41097ab185f..7bcd9b73509 100644 --- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/StructuredTextImpl.java +++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/StructuredTextImpl.java @@ -226,34 +226,39 @@ static public void processSeparator(String text, StructuredTextCharTypes charTyp * LTR base direction, {@link IStructuredTextExpert#leanToFullText * leanToFullText} adds LRE+LRM at the head of the full text and LRM+PDF * at its end. + *

*

* When the orientation is ORIENT_CONTEXTUAL_LTR or * ORIENT_CONTEXTUAL_RTL and the data content would resolve to a * RTL orientation while the structured text has a LTR base direction, * {@link IStructuredTextExpert#leanToFullText leanToFullText} adds LRM at the * head of the full text. + *

*

* When the orientation is ORIENT_CONTEXTUAL_LTR or * ORIENT_CONTEXTUAL_RTL and the data content would resolve to a * LTR orientation while the structured text has a RTL base direction, * {@link IStructuredTextExpert#leanToFullText leanToFullText} adds RLM at the * head of the full text. + *

*

* When the orientation is ORIENT_UNKNOWN and the structured text * has a LTR base direction, {@link IStructuredTextExpert#leanToFullText * leanToFullText} adds LRE+LRM at the head of the full text and LRM+PDF * at its end. + *

*

* When the orientation is ORIENT_UNKNOWN and the structured text * has a RTL base direction, {@link IStructuredTextExpert#leanToFullText * leanToFullText} adds RLE+RLM at the head of the full text and RLM+PDF * at its end. + *

*

* When the orientation is ORIENT_IGNORE, * {@link IStructuredTextExpert#leanToFullText leanToFullText} does not add any * directional formatting characters as either prefix or suffix of the * full text. - *

+ *

*/ @Override public String leanToFullText(String text) { diff --git a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/text/StringMatcher.java b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/text/StringMatcher.java index 1b7db015bfe..d4a32298660 100644 --- a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/text/StringMatcher.java +++ b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/text/StringMatcher.java @@ -128,8 +128,9 @@ public String toString() { * If invoking the StringMatcher with string literals in Java, don't forget * escape characters are represented by "\\". *

- *

+ * An empty pattern matches only an empty text, unless {@link #usePrefixMatch()} + * is used, in which case it always matches. *

* * @param pattern the pattern to match text against, must not be diff --git a/bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/events/MemoryEventConstants.java b/bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/events/MemoryEventConstants.java index 72ce3c4606b..083004995c1 100644 --- a/bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/events/MemoryEventConstants.java +++ b/bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/events/MemoryEventConstants.java @@ -20,7 +20,7 @@ *

* For example, the following handler is registered to handle critical memory * events: - * + *

* 
  * BundleContext context = getContext();
  * EventHandler handler = getHandler();
@@ -28,7 +28,7 @@
  * ht.put(EventConstants.EVENT_TOPIC, MemoryEventConstants.TOPIC_CRITICAL);
  * context.registerService(EventHandler.class.getName(), handler, ht);
  *
- * + *

* There is no policy implemented for sending memory events in Equinox or * Eclipse by default. Another bundle must implement the policy that determines * when to send memory events. This policy must use the Event Admin Service to diff --git a/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/framework/util/SecureAction.java b/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/framework/util/SecureAction.java index 9ead808c195..a7500f00ef4 100644 --- a/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/framework/util/SecureAction.java +++ b/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/framework/util/SecureAction.java @@ -69,12 +69,16 @@ public ClassLoader run() { } /** - * Creates a privileged action that can be used to construct a SecureAction object. - * The recommended way to construct a SecureAction object is the following:

+ * Creates a privileged action that can be used to construct a SecureAction + * object. The recommended way to construct a SecureAction object is the + * following: + * * 

 	 * SecureAction secureAction = (SecureAction) AccessController.doPrivileged(SecureAction.createSecureAction());
 	 *
- * @return a privileged action object that can be used to construct a SecureAction object. + * + * @return a privileged action object that can be used to construct a + * SecureAction object. */ public static PrivilegedAction createSecureAction() { return new PrivilegedAction() { diff --git a/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/bundlefile/BundleFile.java b/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/bundlefile/BundleFile.java index 0f6998cc004..286f50a1d07 100644 --- a/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/bundlefile/BundleFile.java +++ b/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/bundlefile/BundleFile.java @@ -29,12 +29,13 @@ import org.eclipse.osgi.storage.url.bundleresource.Handler; /** - * The BundleFile API is used by Adaptors to read resources out of an - * installed Bundle in the Framework. - *

+ * The BundleFile API is used by Adaptors to read resources out of an installed + * Bundle in the Framework. + *

* Clients wishing to modify or extend the functionality of this class at * runtime should extend the associated {@link BundleFileWrapper decorator} * instead. + *

*/ abstract public class BundleFile { static final SecureAction secureAction = AccessController.doPrivileged(SecureAction.createSecureAction()); diff --git a/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/bundlefile/BundleFileWrapper.java b/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/bundlefile/BundleFileWrapper.java index ee593ebdbb9..a59cccc9aa0 100755 --- a/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/bundlefile/BundleFileWrapper.java +++ b/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/bundlefile/BundleFileWrapper.java @@ -23,12 +23,13 @@ /** * A {@link BundleFile bundle file} decorator. - *

+ *

* Clients wishing to modify or extend the behavior of a bundle file at runtime - * should extend this class instead. A hook is provided by the related {@link - * BundleFileWrapperFactoryHook abstract factory} class in response to a - * {@link BundleFileWrapperFactoryHook#wrapBundleFile(BundleFile, - * BundleInfo.Generation, boolean) call} from the framework. + * should extend this class instead. A hook is provided by the related + * {@link BundleFileWrapperFactoryHook abstract factory} class in response to a + * {@link BundleFileWrapperFactoryHook#wrapBundleFile(BundleFile, BundleInfo.Generation, boolean) + * call} from the framework. + *

*/ public class BundleFileWrapper extends BundleFile { private final BundleFile bundleFile; diff --git a/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/url/reference/Handler.java b/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/url/reference/Handler.java index 69208adc3d2..71603971bfe 100644 --- a/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/url/reference/Handler.java +++ b/bundles/org.eclipse.osgi/container/src/org/eclipse/osgi/storage/url/reference/Handler.java @@ -15,15 +15,18 @@ package org.eclipse.osgi.storage.url.reference; import java.io.IOException; -import java.net.*; +import java.net.URL; +import java.net.URLConnection; +import java.net.URLStreamHandler; /** - * URLStreamHandler for reference protocol. A reference URL is used to hold a - * reference to a local file URL. A reference URL allows bundles to be installed - * by reference. This means the content of the bundle will not be copied. Instead - * the content of the bundle will be loaded from the reference location specified - * by the reference URL. The Framework only supports reference URLs that refer - * to a local file URL. For example:

+ * URLStreamHandler for reference protocol. A reference URL is used to hold a + * reference to a local file URL. A reference URL allows bundles to be installed + * by reference. This means the content of the bundle will not be copied. + * Instead the content of the bundle will be loaded from the reference location + * specified by the reference URL. The Framework only supports reference URLs + * that refer to a local file URL. For example: + * * 

  *     reference:file:/eclipse/plugins/org.eclipse.myplugin_1.0.0/
  *     reference:file:/eclispe/plugins/org.eclipse.mybundle_1.0.0.jar
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/equinox/log/LogFilter.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/equinox/log/LogFilter.java
index aaf6fe4f1ab..9750e5310b6 100644
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/equinox/log/LogFilter.java
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/equinox/log/LogFilter.java
@@ -22,12 +22,13 @@
 public interface LogFilter {
 
 	/**
-	 * @param bundle The logging bundle
-	 * @param loggerName The name of the Logger
-	 * @param logLevel The log level or severity
+	 * @param bundle     The logging bundle
+	 * @param loggerName The name of the Logger
+	 * @param logLevel   The log level or severity
 	 * @see LogEntry
 	 * @see Logger
-	 * @see ExtendedLogReaderService#addLogListener(org.osgi.service.log.LogListener, LogFilter)
+	 * @see ExtendedLogReaderService#addLogListener(org.osgi.service.log.LogListener,
+	 *      LogFilter)
 	 */
 	boolean isLoggable(Bundle bundle, String loggerName, int logLevel);
 }
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/report/resolution/ResolutionReport.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/report/resolution/ResolutionReport.java
index df608aef435..fdf783c6383 100644
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/report/resolution/ResolutionReport.java
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/report/resolution/ResolutionReport.java
@@ -20,72 +20,80 @@
 import org.osgi.service.resolver.ResolutionException;
 
 /**
- * A resolution report is associated with a single resolve process.  Entries
- * contained in a resolution report will contain entries for all resources
- * that were attempted to be resolved in a single resolve process.
- * Resolution reports are gathered by a special type of {@link ResolverHook}
- * which implements the report {@link Listener} interface.  The following
- * example demonstrates how to gather a resolution report for a list of bundles
+ * A resolution report is associated with a single resolve process. Entries
+ * contained in a resolution report will contain entries for all resources that
+ * were attempted to be resolved in a single resolve process. Resolution reports
+ * are gathered by a special type of {@link ResolverHook} which implements the
+ * report {@link Listener} interface. The following example demonstrates how to
+ * gather a resolution report for a list of bundles
+ * 
  * 
-
-	public static ResolutionReport getResolutionReport(Bundle[] bundles, BundleContext context) {
-		DiagReportListener reportListener = new DiagReportListener(bundles);
-		ServiceRegistration hookReg = context.registerService(ResolverHookFactory.class, reportListener, null);
-		try {
-			Bundle systemBundle = context.getBundle(Constants.SYSTEM_BUNDLE_LOCATION);
-			FrameworkWiring frameworkWiring = systemBundle.adapt(FrameworkWiring.class);
-			frameworkWiring.resolveBundles(Arrays.asList(bundles));
-			return reportListener.getReport();
-		} finally {
-			hookReg.unregister();
-		}
-	}
-
-	private static class DiagReportListener implements ResolverHookFactory {
-		private final Collection targetTriggers = new ArrayList();
-		volatile ResolutionReport report = null;
-
-		public DiagReportListener(Bundle[] bundles) {
-			for (Bundle bundle : bundles) {
-				BundleRevision revision = bundle.adapt(BundleRevision.class);
-				if (revision != null && revision.getWiring() == null) {
-					targetTriggers.add(revision);
-				}
-			}
-
-		}
-
-		class DiagResolverHook implements ResolverHook, ResolutionReport.Listener {
-
-			public void handleResolutionReport(ResolutionReport report) {
-				DiagReportListener.this.report = report;
-			}
-
-			public void filterResolvable(Collection candidates) { }
-
-			public void filterSingletonCollisions(BundleCapability singleton,
-					Collection collisionCandidates) { }
-
-			public void filterMatches(BundleRequirement requirement,
-					Collection candidates) { }
-
-			public void end() { }
-
-		}
-		public ResolverHook begin(Collection triggers) {
-			if (triggers.containsAll(targetTriggers)) {
-				// this is the triggers we are looking for
-				return new DiagResolverHook();
-			}
-			// did not find the expected triggers do not participate
-			// in the resolve process to gather the report
-			return null;
-		}
-		ResolutionReport getReport() {
-			return report;
-		}
-	}
+ * 
+ * public static ResolutionReport getResolutionReport(Bundle[] bundles, BundleContext context) {
+ * 	DiagReportListener reportListener = new DiagReportListener(bundles);
+ * 	ServiceRegistration<ResolverHookFactory> hookReg = context.registerService(ResolverHookFactory.class,
+ * 			reportListener, null);
+ * 	try {
+ * 		Bundle systemBundle = context.getBundle(Constants.SYSTEM_BUNDLE_LOCATION);
+ * 		FrameworkWiring frameworkWiring = systemBundle.adapt(FrameworkWiring.class);
+ * 		frameworkWiring.resolveBundles(Arrays.asList(bundles));
+ * 		return reportListener.getReport();
+ * 	} finally {
+ * 		hookReg.unregister();
+ * 	}
+ * }
+ * 
+ * private static class DiagReportListener implements ResolverHookFactory {
+ * 	private final Collection<BundleRevision> targetTriggers = new ArrayList<BundleRevision>();
+ * 	volatile ResolutionReport report = null;
+ * 
+ * 	public DiagReportListener(Bundle[] bundles) {
+ * 		for (Bundle bundle : bundles) {
+ * 			BundleRevision revision = bundle.adapt(BundleRevision.class);
+ * 			if (revision != null && revision.getWiring() == null) {
+ * 				targetTriggers.add(revision);
+ * 			}
+ * 		}
+ * 
+ * 	}
+ * 
+ * 	class DiagResolverHook implements ResolverHook, ResolutionReport.Listener {
+ * 
+ * 		public void handleResolutionReport(ResolutionReport report) {
+ * 			DiagReportListener.this.report = report;
+ * 		}
+ * 
+ * 		public void filterResolvable(Collection<BundleRevision> candidates) {
+ * 		}
+ * 
+ * 		public void filterSingletonCollisions(BundleCapability singleton,
+ * 				Collection<BundleCapability> collisionCandidates) {
+ * 		}
+ * 
+ * 		public void filterMatches(BundleRequirement requirement, Collection<BundleCapability> candidates) {
+ * 		}
+ * 
+ * 		public void end() {
+ * 		}
+ * 
+ * 	}
+ * 
+ * 	public ResolverHook begin(Collection<BundleRevision> triggers) {
+ * 		if (triggers.containsAll(targetTriggers)) {
+ * 			// this is the triggers we are looking for
+ * 			return new DiagResolverHook();
+ * 		}
+ * 		// did not find the expected triggers do not participate
+ * 		// in the resolve process to gather the report
+ * 		return null;
+ * 	}
+ * 
+ * 	ResolutionReport getReport() {
+ * 		return report;
+ * 	}
+ * }
  * 

+ * 
  * @since 3.10
  */
 public interface ResolutionReport {