You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@netbeans.apache.org by sk...@apache.org on 2023/01/09 15:25:05 UTC
[netbeans] branch master updated: apidoc error/warning fix
This is an automated email from the ASF dual-hosted git repository.
skygo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/netbeans.git
The following commit(s) were added to refs/heads/master by this push:
new 126c1b4f4f apidoc error/warning fix
new cd38f5aee3 Merge pull request #5216 from ebarboni/apidocsanitize1
126c1b4f4f is described below
commit 126c1b4f4f573525da32fb97ae09aa9da6ae5830
Author: Eric Barboni <sk...@apache.org>
AuthorDate: Thu Jan 5 18:43:26 2023 +0100
apidoc error/warning fix
---
platform/api.annotations.common/arch.xml | 2 +-
.../api/annotations/common/StaticResource.java | 2 +
.../api/annotations/common/SuppressWarnings.java | 1 +
platform/api.scripting/apichanges.xml | 2 +-
platform/api.scripting/arch.xml | 6 +--
platform/openide.util.lookup/apichanges.xml | 4 +-
platform/openide.util.lookup/arch.xml | 9 ++--
.../src/org/openide/util/Lookup.java | 24 ++++++----
.../org/openide/util/lookup/AbstractLookup.java | 3 ++
.../org/openide/util/lookup/InstanceContent.java | 10 ++++-
.../src/org/openide/util/lookup/Lookups.java | 25 +++++++----
.../util/lookup/NamedServiceDefinition.java | 11 +++--
.../src/org/openide/util/lookup/ProxyLookup.java | 1 -
.../org/openide/util/lookup/ServiceProvider.java | 4 ++
.../org/openide/util/lookup/ServiceProviders.java | 1 +
.../org/openide/util/lookup/doc-files/index.html | 12 ++---
.../openide/util/lookup/doc-files/lookup-api.html | 2 +-
platform/openide.util/arch.xml | 4 +-
.../src/org/openide/util/BaseUtilities.java | 24 +++++-----
.../src/org/openide/util/EditableProperties.java | 4 +-
.../src/org/openide/util/Enumerations.java | 21 ++++++---
.../src/org/openide/util/Exceptions.java | 7 +--
.../src/org/openide/util/MapFormat.java | 18 ++++++--
.../openide.util/src/org/openide/util/Mutex.java | 23 +++++-----
.../src/org/openide/util/MutexException.java | 6 +--
.../src/org/openide/util/NbBundle.java | 41 ++++++++---------
.../src/org/openide/util/NbCollections.java | 11 +++++
.../src/org/openide/util/RequestProcessor.java | 52 +++++++++++-----------
.../openide.util/src/org/openide/util/Task.java | 6 +--
.../org/openide/util/TopologicalSortException.java | 2 +-
.../openide/util/URLStreamHandlerRegistration.java | 2 +
.../openide.util/src/org/openide/util/Union2.java | 4 ++
.../src/org/openide/util/WeakListeners.java | 18 ++++----
.../src/org/openide/util/doc-files/api.html | 6 +--
.../org/openide/util/doc-files/preferences.html | 10 ++---
.../org/openide/util/io/NbObjectInputStream.java | 6 +--
.../org/openide/util/io/OperationException.java | 1 +
.../src/org/openide/util/io/ReaderInputStream.java | 4 +-
.../src/org/openide/util/io/SafeException.java | 1 +
.../src/org/openide/xml/EntityCatalog.java | 9 ++--
.../openide.util/src/org/openide/xml/XMLUtil.java | 21 +++++----
41 files changed, 253 insertions(+), 167 deletions(-)
diff --git a/platform/api.annotations.common/arch.xml b/platform/api.annotations.common/arch.xml
index 4eb847d8ab..8bca98a053 100644
--- a/platform/api.annotations.common/arch.xml
+++ b/platform/api.annotations.common/arch.xml
@@ -480,7 +480,7 @@
<answer id="deploy-packages">
<p>
Only API packages are exported. JDK bug workarounded in build harness
- (<a href="http://www.netbeans.org/issues/show_bug.cgi?id=152562">#152562</a>).
+ (<a href="https://bz.apache.org/netbeans/show_bug.cgi?id=152562">#152562</a>).
</p>
</answer>
diff --git a/platform/api.annotations.common/src/org/netbeans/api/annotations/common/StaticResource.java b/platform/api.annotations.common/src/org/netbeans/api/annotations/common/StaticResource.java
index 9233217a6c..0339c644ff 100644
--- a/platform/api.annotations.common/src/org/netbeans/api/annotations/common/StaticResource.java
+++ b/platform/api.annotations.common/src/org/netbeans/api/annotations/common/StaticResource.java
@@ -42,6 +42,7 @@ public @interface StaticResource {
/**
* If true, permit the resource to be in the classpath.
* By default, it may only be in the sourcepath.
+ * @return true to search in classpath
*/
boolean searchClasspath() default false;
@@ -49,6 +50,7 @@ public @interface StaticResource {
* If true, consider the resource path to be relative to the current package.
* ({@code ../} sequences are permitted.)
* By default, it must be an absolute path (not starting with {@code /}).
+ * @return true to consider resource path to be relative to current package
*/
boolean relative() default false;
diff --git a/platform/api.annotations.common/src/org/netbeans/api/annotations/common/SuppressWarnings.java b/platform/api.annotations.common/src/org/netbeans/api/annotations/common/SuppressWarnings.java
index f987f37fd9..bcfef953ca 100644
--- a/platform/api.annotations.common/src/org/netbeans/api/annotations/common/SuppressWarnings.java
+++ b/platform/api.annotations.common/src/org/netbeans/api/annotations/common/SuppressWarnings.java
@@ -36,6 +36,7 @@ public @interface SuppressWarnings {
/**
* The names of the warnings to suppress.
+ * @return list of warning to supress
*/
String[] value() default {};
diff --git a/platform/api.scripting/apichanges.xml b/platform/api.scripting/apichanges.xml
index 3ce0e4585e..10d3c238de 100644
--- a/platform/api.scripting/apichanges.xml
+++ b/platform/api.scripting/apichanges.xml
@@ -62,7 +62,7 @@
<a href="@TOP@/org/netbeans/api/scripting/Scripting.html">Scripting.createManager()</a>
to obtain enhanced version of
<a href="@JDK@/javax/script/ScriptEngineManager.html">ScriptEngineManager</a>
- that can work well with <a href="http://graalvm.org">GraalVM</a>
+ that can work well with <a href="https://graalvm.org">GraalVM</a>
languages registered via
<a href="@TOP@/org/netbeans/spi/scripting/EngineProvider.html">EngineProvider</a>
</description>
diff --git a/platform/api.scripting/arch.xml b/platform/api.scripting/arch.xml
index d9c571e652..38bb0a690d 100644
--- a/platform/api.scripting/arch.xml
+++ b/platform/api.scripting/arch.xml
@@ -61,7 +61,7 @@
<!--
<question id="arch-quality" when="init">
- How will the <a href="http://www.netbeans.org/community/guidelines/q-evangelism.html">quality</a>
+ How will the <a href="https://netbeans.apache.org/participate/qualityevangelism.html">quality</a>
of your code be tested and
how are future regressions going to be prevented?
<hint>
@@ -153,13 +153,13 @@
<a href="@TOP@/org/netbeans/api/scripting/Scripting.html">Scripting</a>
factory methods. Alternatively you can implement and register
<a href="@TOP@/org/netbeans/spi/scripting/EngineProvider.html">EngineProvider</a>
- as in the <a href="#java-org.netbeans.spi.scripting">dynamic registration use-case</a>.
+ as in the <a href="@TOP@architecture-summary.html#java-org.netbeans.spi.scripting">dynamic registration use-case</a>.
</p>
<p>
In any case don't forget to advertise your engine to the
<a href="@org-openide-modules@/overview-summary.html">runtime container</a>
via <code>OpenIDE-Module-Providers: javax.script.ScriptEngine."engineName"</code>
- tag as specified by <a href="#property-manifest.ScriptEngine">manifest registration</a>
+ tag as specified by <a href="@TOP@architecture-summary.html#property-manifest.ScriptEngine">manifest registration</a>
API.
</p>
</usecase>
diff --git a/platform/openide.util.lookup/apichanges.xml b/platform/openide.util.lookup/apichanges.xml
index f3d71c3fa8..7b35bf2ece 100644
--- a/platform/openide.util.lookup/apichanges.xml
+++ b/platform/openide.util.lookup/apichanges.xml
@@ -73,7 +73,7 @@
<a href="@JDK@/javax/lang/model/SourceVersion.html#latest--"><code>@SourceVersion.latest()</code></a>.
</p>
</description>
- <class name="LayerGeneratingProcessor" package="org.openide.filesystems.annotations"/>
+ <class name="LayerGeneratingProcessor" package="org.openide.filesystems.annotations" link="no" /> <!-- external -->
<issue number="NETBEANS-3250"/>
</change>
<change id="lookups.execute">
@@ -440,7 +440,7 @@ for (<a href="@JDK@/java/net/URLStreamHandlerFactory.html">URLStreamHandlerFacto
<description>
The content of <code>Lookup.getDefault()</code> can be specified
by a standard JDK registration mechanism, using JARs'
- <a href="http://java.sun.com/j2se/1.4/docs/guide/jar/jar.html#Service%20Provider" shape="rect">
+ <a href="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Service%20Provider" shape="rect">
META-INF/services
</a>
directory. This is suitable for services that do not change,
diff --git a/platform/openide.util.lookup/arch.xml b/platform/openide.util.lookup/arch.xml
index 6e50e72dd2..ed2363da39 100644
--- a/platform/openide.util.lookup/arch.xml
+++ b/platform/openide.util.lookup/arch.xml
@@ -49,7 +49,7 @@
<answer id="arch-quality">
<p>
There is a lot of unit tests in
- <a href="http://hg.netbeans.org/main-golden/openide.util.lookup/test/unit/src/">version control</a>
+ <a href="https://github.com/apache/netbeans/tree/master/platform/openide.util.lookup/test/unit/src">version control</a>
system.
</p>
</answer>
@@ -64,7 +64,7 @@
<answer id="arch-usecases">
- <a onclick="target='_blank'" href="https://leanpub.com/nbp4beginners">
+ <a href="https://leanpub.com/nbp4beginners">
<img src="http://wiki.apidesign.org/images/0/03/NetBeansPlatformForBeginners.jpg"
style="float: right"
width="60" height="70" alt="Cover of NetBeans Platform for Beginners book"/>
@@ -74,7 +74,7 @@
<a href="@TOP@/org/openide/util/Lookup.html">javadoc</a>.
For details on this topic,
together with code samples, see chapter 4,
- of <a onclick="target='_blank'" href="https://leanpub.com/nbp4beginners">NetBeans Platform for Beginners</a>
+ of <a href="https://leanpub.com/nbp4beginners">NetBeans Platform for Beginners</a>
by Jason Wexbridge and Walter Nyland.
In addition to that here is
a list of frequently asked or interesting questions slowly expanding as
@@ -214,9 +214,10 @@ org.my.netbeans.extramodule.ExtraTip
<api name="ProviderRegistrationMechanism"
type="import"
category="standard"
- url="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File"
+ url="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Provider%20Configuration%20File"
group="java"
/>
+ <!-- ref to 1.5.0 as 1.3 is not reacheable -->
but enhances it to also support the
<api
name="ProviderRegistrationRemoval"
diff --git a/platform/openide.util.lookup/src/org/openide/util/Lookup.java b/platform/openide.util.lookup/src/org/openide/util/Lookup.java
index a22e4566a9..5c053c724f 100644
--- a/platform/openide.util.lookup/src/org/openide/util/Lookup.java
+++ b/platform/openide.util.lookup/src/org/openide/util/Lookup.java
@@ -36,12 +36,12 @@ import org.openide.util.lookup.ServiceProvider;
* A general registry permitting clients to find instances of services
* (implementation of a given interface).
* This class is inspired by the
- * <a href="http://www.jini.org/">Jini</a>
+ * <a href="https://river.apache.org">Jini</a>
* registration and lookup mechanism. The difference is that the methods do
* not throw checked exceptions (as they usually work only locally and not over the network)
* and that the Lookup API concentrates on the lookup, not on the registration
- * (although {@link Lookup#getDefault} is strongly encouraged to support
- * {@link Lookups#metaInfServices} for registration in addition to whatever
+ * (although {@link Lookup#getDefault()} is strongly encouraged to support
+ * {@link Lookups#metaInfServices(java.lang.ClassLoader) } for registration in addition to whatever
* else it decides to support).
* <p>
* For a general talk about the idea behind the lookup pattern please see
@@ -222,7 +222,8 @@ public abstract class Lookup {
* If more than one object matches, the first will be returned.
* The template class may be a class or interface; the instance is
* guaranteed to be assignable to it.
- *
+ *
+ * @param <T> type of interface we are searching for
* @param clazz class of the object we are searching for
* @return an object implementing the given class or <code>null</code> if no such
* implementation is found
@@ -236,7 +237,8 @@ public abstract class Lookup {
* specify whether subsequent calls with the same template produce new
* instance of the {@link Lookup.Result} or return shared instance. The
* prefered behaviour however is to return shared one.
- *
+ *
+ * @param <T> type of interface we are searching for
* @param template a template describing the services to look for
* @return an object containing the results
*/
@@ -244,6 +246,8 @@ public abstract class Lookup {
/** Look up the first item matching a given template.
* Includes not only the instance but other associated information.
+ *
+ * @param <T> type of interface we are searching for
* @param template the template to check
* @return a matching item or <code>null</code>
*
@@ -259,6 +263,8 @@ public abstract class Lookup {
* Find a result corresponding to a given class.
* Equivalent to calling {@link #lookup(Lookup.Template)} but slightly more convenient.
* Subclasses may override this method to produce the same semantics more efficiently.
+ *
+ * @param <T> type of interface we are searching for
* @param clazz the supertype of the result
* @return a live object representing instances of that type
* @since org.openide.util 6.10
@@ -447,10 +453,10 @@ public abstract class Lookup {
public abstract static class Result<T> extends Object {
/** Registers a listener that is invoked when there is a possible
* change in this result.
- * <p>
+ *
* <div class="nonnormative">
* Sometimes people report that their listener is not receiving
- * events (for example <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=191471">IZ 191471</a>)
+ * events (for example <a href="https://bz.apache.org/netbeans/show_bug.cgi?id=191471">IZ 191471</a>)
* or that the listener receives few events, but then it <em>stops</em>
* listening.
* Such behavior is often caused by not keeping strong reference to
@@ -473,7 +479,7 @@ public abstract class Lookup {
* should be {@link List} as the order matters, but the {@link Collection}
* is kept for compatibility reasons) of all instances present in
* the {@link Result} right now that will never change its content.
- * <p></p>
+ *
* <div class="nonnormative">
* While the returned collection never changes its content, some
* implementation like {@link ProxyLookup} may
@@ -505,7 +511,7 @@ public abstract class Lookup {
* should be {@link List} as the order matters, but the {@link Collection}
* is kept for compatibility reasons) of all {@link Item items} present in
* the {@link Result} right now that will never change its content.
- * <p></p>
+ *
* <div class="nonnormative">
* While the returned collection never changes its content, some
* implementation like {@link ProxyLookup} may
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/AbstractLookup.java b/platform/openide.util.lookup/src/org/openide/util/lookup/AbstractLookup.java
index 10a7847a3c..ae8db94cad 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/AbstractLookup.java
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/AbstractLookup.java
@@ -841,6 +841,9 @@ public class AbstractLookup extends Lookup implements Serializable {
* <p>Typically this will produce the same result as
* {@code c.isAssignableFrom(}{@link #getType() getType}{@code ())}
* but may avoid loading the concrete type's class in doing so.
+ *
+ * @param c class to check against
+ * @return true if this item can produce object of class c
*/
protected abstract boolean instanceOf(Class<?> c);
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/InstanceContent.java b/platform/openide.util.lookup/src/org/openide/util/lookup/InstanceContent.java
index 28fbfd558b..2c2a5815da 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/InstanceContent.java
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/InstanceContent.java
@@ -31,7 +31,7 @@ import org.openide.util.Lookup.Item;
* and provides methods for registration of instances and lazy instances.
* <PRE>
* {@link InstanceContent} ic = new {@link InstanceContent#InstanceContent() InstanceContent()};
- * {@link Lookup} lookup = new {@link AbstractLookup#AbstractLookup(org.openide.util.lookup.AbstractLookup.Content) AbstractLookup(ic)};
+ * {@link org.openide.util.Lookup} lookup = new {@link AbstractLookup#AbstractLookup(org.openide.util.lookup.AbstractLookup.Content) AbstractLookup(ic)};
*
* ic.{@link #add(java.lang.Object) add(new Object ())};
* ic.{@link #add(java.lang.Object) add(new Dimension (...))};
@@ -81,7 +81,9 @@ public final class InstanceContent extends AbstractLookup.Content {
* <p>
* To remove registered object from lookup use {@link #remove(java.lang.Object, org.openide.util.lookup.InstanceContent.Convertor)}
* with the same arguments.
- *
+ *
+ * @param <T> type of instance
+ * @param <R> type to convert instance to
* @param inst instance
* @param conv convertor which postponing an instantiation,
* if <code>conv==null</code> then the instance is registered directly.
@@ -98,6 +100,8 @@ public final class InstanceContent extends AbstractLookup.Content {
}
/** Remove instance added with a convertor.
+ * @param <T> type of instance
+ * @param <R> type to convert instance to
* @param inst instance
* @param conv convertor, if <code>conv==null</code> it is same like
* remove(Object)
@@ -108,6 +112,8 @@ public final class InstanceContent extends AbstractLookup.Content {
/** Changes all pairs in the lookup to new values. Converts collection of
* instances to collection of pairs.
+ * @param <T> type of instance
+ * @param <R> type to convert instance to
* @param col the collection of (Item) objects
* @param conv the convertor to use or null
*/
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/Lookups.java b/platform/openide.util.lookup/src/org/openide/util/lookup/Lookups.java
index f4f81330ef..dfaa2be7e6 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/Lookups.java
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/Lookups.java
@@ -41,6 +41,7 @@ public class Lookups {
* either return the object or null if the supplied template does
* not match the class. If the specified argument is null the method
* will end with NullPointerException.
+ * @param objectToLookup object to lookup
* @return Fully initialized lookup object ready to use
* @throws NullPointerException if the supplied argument is null
* @since 2.21
@@ -91,6 +92,10 @@ public class Lookups {
* Its contents never changes so registering listeners on such lookup
* does not have any observable effect (the listeners are never called).
*
+ * @param <T> type for key
+ * @param <R> type for result
+ * @param keys set of object
+ * @param convertor convertor for object
* @return Fully initialized lookup object ready to use
* @throws NullPointerException if the any of the arguments is null
* @since 2.21
@@ -122,7 +127,7 @@ public class Lookups {
* to notify listeners on the lookup about that it should trigger the event
* firing, for example by calling <code>lookup.lookup (Object.class)</code>
* directly on the lookup returned by this method
- * that forces a check of the return value of {@link org.openide.util.Lookup.Provider#getLookup}</code>.
+ * that forces a check of the return value of {@link org.openide.util.Lookup.Provider#getLookup}.
*
* @param provider the provider that returns a lookup to delegate to
* @return lookup delegating to the lookup returned by the provider
@@ -146,6 +151,8 @@ public class Lookups {
* Existing instances will be kept if the implementation classes are unchanged,
* so there is "stability" in doing this provided some parent loaders are the same
* as the previous ones.
+ * @param classLoader class loader to use for loading
+ * @return lookup associatied with classloader
* @since 3.35
* @see ServiceProvider
*/
@@ -158,6 +165,7 @@ public class Lookups {
* from the specified prefix.
* @param classLoader class loader to use for loading
* @param prefix prefix to prepend to the class name when searching
+ * @return lookup associatied with classloader
* @since 7.9
* @see ServiceProvider#path
*/
@@ -165,10 +173,10 @@ public class Lookups {
return new MetaInfServicesLookup(classLoader, prefix);
}
- /** Creates a <q>named</q> lookup.
+ /** Creates a <code>named</code> lookup.
* It is a lookup identified by a given path.
* Two lookups with the same path should have the same content.
- * <p>It is expected that each <q>named</q> lookup
+ * <p>It is expected that each <code>named</code> lookup
* will contain a superset of what would be created by:
* <code>{@linkplain #metaInfServices(ClassLoader,String) metaInfServices}(theRightLoader, "META-INF/namedservices/" + path + "/")</code>
*
@@ -177,7 +185,7 @@ public class Lookups {
* {@link Lookups#forPath(java.lang.String)} can combine lookups
* from several sources. In current NetBeans Runtime Container, two lookups are used:
* </p>
- * <ul class="nonnormative">
+ * <ul>
* <li><code>Lookups.metaInfServices("META-INF/namedservices/" + path)</code></li>
* <li><code>org.openide.loaders.FolderLookup(path)</code></li>
* </ul>
@@ -232,12 +240,13 @@ public class Lookups {
* assertEquals("Returns C as A.class is not between B and C", c, l2.lookup(B.class));
* </pre>
* For more info check the
- * <a href="http://hg.netbeans.org/main-golden/annotate/4883eaeda744/openide.util/test/unit/src/org/openide/util/lookup/ExcludingLookupTest.java">
+ * <a href="https://github.com/apache/netbeans/tree/master/platform/openide.util.lookup/test/unit/src/org/openide/util/lookup/ExcludingLookupTest.java">
* excluding lookup tests</a> and the discussion in issue
- * <a href="http://openide.netbeans.org/issues/show_bug.cgi?id=53058">53058</a>.
+ * <a href="https://bz.apache.org/netbeans/show_bug.cgi?id=53058">53058</a>.
*
* @param lookup the original lookup that should be filtered
* @param classes array of classes those instances should be excluded
+ * @return filtred lookup
* @since 5.4
*/
public static Lookup exclude(Lookup lookup, Class... classes) {
@@ -245,7 +254,7 @@ public class Lookups {
}
/** Creates <code>Lookup.Item</code> representing the instance passed in.
- *
+ * @param <T> type of the object
* @param instance the object for which Lookup.Item should be creted
* @param id unique identification of the object, for details see {@link org.openide.util.Lookup.Item#getId},
* can be <code>null</code>
@@ -260,7 +269,7 @@ public class Lookups {
* of {@link Lookup#getDefault()} to here-in provided lookup. Useful in a
* multi user environment where different users and their requests should
* be associated with different content of default lookup.
- * <p/>
+ * <p>
* As a special case, {@code executeWith} will execute the Runnable with
* the system global lookup (the one effective during system bootstrap), when
* the passed {@code defaultLookup} parameter is {@code null}. This feature may
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/NamedServiceDefinition.java b/platform/openide.util.lookup/src/org/openide/util/lookup/NamedServiceDefinition.java
index 0e94c3d812..ac2bc3bdcc 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/NamedServiceDefinition.java
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/NamedServiceDefinition.java
@@ -34,12 +34,12 @@ import java.lang.annotation.Target;
* to verify the annotated type is subclass of <code>URLStreamHandler</code> and
* if so, register it into <code>URLStreamHandler/@protocol</code> where the
* value of <code>@protocol()</code> is replaced by the value of annotation's
- * <a href="@org-openide-util@/org/openide/util/URLStreamHandlerRegistration.html#protocol()">
+ * <a href="@org-openide-util@/org/openide/util/URLStreamHandlerRegistration.html#protocol--">
* protocol attribute</a>. The registration can later be found by using
* {@link Lookups#forPath(java.lang.String) Lookups.forPath("URLStreamHandler/ftp")}
* (in case the protocol was ftp).
*
- * @author Jaroslav Tulach <jt...@netbeans.org>
+ * @author Jaroslav Tulach <jtulach@netbeans.org>
* @since 8.14
* @see ServiceProvider#path()
*/
@@ -49,6 +49,7 @@ public @interface NamedServiceDefinition {
/** Type, or array of types that the registered type
* has to implement. The annotated type needs to register at least
* one of the enumerated classes.
+ * @return set of type
*/
public Class<?>[] serviceType();
/** Path to register the annotation to, so it can later be found by
@@ -59,6 +60,7 @@ public @interface NamedServiceDefinition {
* These attributes must be of type <code>String</code>
* or array of <code>String</code>s (then one registration is performed
* per each string in the array).
+ * @return path to register annotation
*/
public String path();
/** Name of attribute that specifies position. By default the system tries
@@ -68,8 +70,9 @@ public @interface NamedServiceDefinition {
* name by specifying non-default here. Should the position be ignored,
* specify empty string.
*
- * @param name of attribute in the annotated annotation to use for defining
- * position of the registration. The attribute should return int value.
+ * name of attribute in the annotated annotation to use for defining
+ * position of the registration. The attribute should return int value.
+ * @return position
*/
public String position() default "-";
}
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/ProxyLookup.java b/platform/openide.util.lookup/src/org/openide/util/lookup/ProxyLookup.java
index 2779fdbab6..1c695149f4 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/ProxyLookup.java
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/ProxyLookup.java
@@ -151,7 +151,6 @@ public class ProxyLookup extends Lookup {
* If called before a {@link ProxyLookup} has been attached to this
* controller, an IllegalStateException will be thrown.
*
- * @param exe An executor to notify in
* @param lookups An array of Lookups to be proxied
* @throws IllegalStateException if called before this instance
* has been passed to the constructor of (exactly one) {@link ProxyLookup}
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/ServiceProvider.java b/platform/openide.util.lookup/src/org/openide/util/lookup/ServiceProvider.java
index d6c8f72d6f..13da72e7a9 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/ServiceProvider.java
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/ServiceProvider.java
@@ -54,6 +54,7 @@ public @interface ServiceProvider {
* <p>Requests to look up the specified interface should result in this implementation.
* Requests for any other types may or may not result in this implementation even if the
* implementation is assignable to those types.
+ * @return type to register this implementation
*/
Class<?> service();
@@ -61,6 +62,7 @@ public @interface ServiceProvider {
* An optional position in which to register this service relative to others.
* Lower-numbered services are returned in the lookup result first.
* Services with no specified position are returned last.
+ * @return position to register the service
*/
int position() default Integer.MAX_VALUE;
@@ -71,6 +73,7 @@ public @interface ServiceProvider {
*
* <p><i>Note:</i> Dollar sign ($) is used in inner class names. For example
* <code>org.netbeans.modules.openfile.FileChooser$JavaFilesFilter</code>.</p>
+ * @return set of implementations this implementation supersedes
*/
String[] supersedes() default {};
@@ -86,6 +89,7 @@ public @interface ServiceProvider {
* The {@link NamedServiceDefinition} offers various benefits over
* plain {@link #path()} usage including type checking and lower
* possibility of typos.
+ * @return path to register implementation
*/
String path() default "";
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/ServiceProviders.java b/platform/openide.util.lookup/src/org/openide/util/lookup/ServiceProviders.java
index 98015f9d28..2cb2b9eb9f 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/ServiceProviders.java
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/ServiceProviders.java
@@ -34,6 +34,7 @@ public @interface ServiceProviders {
/**
* List of service provider registrations.
+ * @return list of service provider
*/
ServiceProvider[] value();
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/doc-files/index.html b/platform/openide.util.lookup/src/org/openide/util/lookup/doc-files/index.html
index 2d1fe923e1..8240b573c8 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/doc-files/index.html
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/doc-files/index.html
@@ -35,7 +35,7 @@ and how other parts of the system can <b>look</b> them <b>up</B>.
<P>
There already are libraries trying to solve this problem, usually by querying for
an interface and finding its appropriate implementaion. The most famous is
-<A href="http://www.jini.org/">Jini</A>, the platform for development of
+<A href="https://river.apache.org">Jini</A>, the platform for development of
distributed network services. Our library does something similar, but tries
to stay small and easy
to use. The NetBeans <em>Lookup
@@ -87,7 +87,7 @@ It would be much nicer if the registation could be done just by putting a JAR fi
into the application classpath.
<P>
Actually this has been realized also by the JDK development team and addressed in
-JDK 1.3 as part of the <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File">provider extension mechanism</A>.
+JDK 1.3 as part of the <a href="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Provider%20Configuration%20File">provider extension mechanism</A>.
The <code>MyToolkit</code> could be registered by adding a file
<code>/META-INF/services/java.awt.Toolkit</code> with one line
<code>org.myorg.MyToolkit</code> into the JAR file that contains the
@@ -176,13 +176,13 @@ Specifying the query, getting the result and listenning on changes.</LI>
<LI><A HREF="lookup-spi.html">Lookup Library SPIs</A> for those writing the
implementaion code and registering it with lookup. Includes also writing own
lookup implementation.</LI>
- <LI>Download <A HREF="http://www.netbeans.org/">NetBeans platform</A> which
+ <LI>Download <A HREF="https://netbeans.apache.org/download/index.html">NetBeans platform</A> which
contains <code>org-openide-util.jar</code></LI>
- <A HREF="http://hg.netbeans.org/main-golden/file/tip/openide.util/src/org/openide/util/lookup/">
+ <A HREF="https://github.com/apache/netbeans/tree/master/platform/openide.util.lookup/src/org/openide/util/lookup">
implementation package (org.openide.util.lookup) </A>
+ classes Lookup, LookupEvent, LookupListener in
- <A href="http://hg.netbeans.org/main-golden/file/tip/openide.util/src/org/openide/util/">util package</A></LI>
- <li><a href="http://www.martinfowler.com/articles/injection.html">Inversion of Control Containers and the Dependency Injection pattern</a> (Martin Fowler)</li>
+ <A href="https://github.com/apache/netbeans/tree/master/platform/openide.util.lookup/src/org/openide/util">util package</A></LI>
+ <li><a href="https://www.martinfowler.com/articles/injection.html">Inversion of Control Containers and the Dependency Injection pattern</a> (Martin Fowler)</li>
</UL>
</BODY>
</HTML>
diff --git a/platform/openide.util.lookup/src/org/openide/util/lookup/doc-files/lookup-api.html b/platform/openide.util.lookup/src/org/openide/util/lookup/doc-files/lookup-api.html
index 5106dbe529..33b6ed6d40 100644
--- a/platform/openide.util.lookup/src/org/openide/util/lookup/doc-files/lookup-api.html
+++ b/platform/openide.util.lookup/src/org/openide/util/lookup/doc-files/lookup-api.html
@@ -49,7 +49,7 @@ Javadoc there is a static method
The object returned from this method is
a global lookup that can serve as a central place for registering services.
The default implementation is a lookup that implements
-<a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider">
+<a href="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Service%20Provider">
the JDK JAR services</A>
mechanism and delegates to <samp>META-INF/services/name.of.Class</samp> files.
<P>
diff --git a/platform/openide.util/arch.xml b/platform/openide.util/arch.xml
index a8fcaae82b..433df5941d 100644
--- a/platform/openide.util/arch.xml
+++ b/platform/openide.util/arch.xml
@@ -57,7 +57,7 @@
<answer id="arch-quality">
<p>
There is a lot of unit tests in
- <a href="http://hg.netbeans.org/main-golden/openide.util/test/unit/src/">version control</a>
+ <a href="https://github.com/apache/netbeans/tree/master/platform/openide.util/test/unit/src/">version control</a>
system.
</p>
</answer>
@@ -240,7 +240,7 @@
</answer>
<answer id="format-types">
<p>
- The <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File">META-INF/services/...</a> files.
+ The <a href="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Provider%20Configuration%20File">META-INF/services/...</a> files.
<api name="TranslateNames" category="official" type="export" group="java.io.File"
url="@TOP@/org/openide/util/BaseUtilities.html#translate-java.lang.String-">
<a href="@TOP@/org/openide/util/BaseUtilities.html#translate-java.lang.String-">Utilities.translate</a>
diff --git a/platform/openide.util/src/org/openide/util/BaseUtilities.java b/platform/openide.util/src/org/openide/util/BaseUtilities.java
index 9f1f5ee9d8..045cdf8a5f 100644
--- a/platform/openide.util/src/org/openide/util/BaseUtilities.java
+++ b/platform/openide.util/src/org/openide/util/BaseUtilities.java
@@ -174,10 +174,10 @@ public abstract class BaseUtilities {
* In order to provide useful support for this problem, this queue has been
* provided.
* <P>
- * If you have a reference that needs cleanup, make it implement <link>Runnable</link>
+ * If you have a reference that needs cleanup, make it implement {@link Runnable}
* and register it with the queue:
* <PRE>
- * class MyReference extends WeakReference<Thing> implements Runnable {
+ * class MyReference extends WeakReference<Thing> implements Runnable {
* private final OtherInfo dataToCleanUp;
* public MyReference(Thing ref, OtherInfo data) {
* super(ref, Utilities.queue());
@@ -200,6 +200,7 @@ public abstract class BaseUtilities {
* <p>
* Be sure to call this method anew for each reference.
* Do not attempt to cache the return value.
+ * @return reference queue
* @since 3.11
*/
public static ReferenceQueue<Object> activeReferenceQueue() {
@@ -1014,9 +1015,9 @@ widthcheck: {
* <li>Include command names with embedded spaces, such as <code>c:\Program Files\jdk\bin\javac</code>.
* <li>Include extra command arguments, such as <code>-Dname=value</code>.
* <li>Do anything else which might require unusual characters or processing. For example:
- * <p><code><pre>
+ * <p><code>
* "c:\program files\jdk\bin\java" -Dmessage="Hello /\\/\\ there!" -Xmx128m
- * </pre></code>
+ * </code>
* <p>This example would create the following executable name and arguments:
* <ol>
* <li> <code>c:\program files\jdk\bin\java</code>
@@ -1118,6 +1119,8 @@ widthcheck: {
}
/** Complementary method to parseParameters
+ * @param params set of parameters
+ * @return escaped parameters
* @see #parseParameters
*/
public static String escapeParameters(String[] params) {
@@ -1199,6 +1202,7 @@ widthcheck: {
* order as the incoming elements. However if some elements need to be rearranged,
* it is <em>not</em> guaranteed that others will not also be rearranged, even
* if they did not strictly speaking need to be.
+ * @param <T> tyupe of element
* @param c a collection of objects to be topologically sorted
* @param edges constraints among those objects, of type <code>Map<Object,Collection></code>;
* if an object is a key in this map, the resulting order will
@@ -1207,7 +1211,7 @@ widthcheck: {
* @exception TopologicalSortException if the sort cannot succeed due to cycles in the graph, the
* exception contains additional information to describe and possibly recover from the error
* @since 3.30
- * @see <a href="http://www.netbeans.org/issues/show_bug.cgi?id=27286">Issue #27286</a>
+ * @see <a href="https://bz.apache.org/netbeans/show_bug.cgi?id=27286">Issue #27286</a>
*/
public static <T> List<T> topologicalSort(Collection<? extends T> c, Map<? super T, ? extends Collection<? extends T>> edges)
throws TopologicalSortException {
@@ -1344,24 +1348,24 @@ widthcheck: {
* Btw. one can use spaces instead of <code>=</code> sign.
* For a real world example
* check the
- * <a href="http://www.netbeans.org/source/browse/xml/text-edit/compat/src/META-INF/netbeans/">
+ * <a href="https://github.com/apache/netbeans/tree/master/ide/xml">
* xml module</a>.
*
* <P>
- * For purposes of <link>org.openide.util.io.NbObjectInputStream</link> there is
+ * For purposes of {@link org.openide.util.io.NbObjectInputStream} there is
* a following special convention:
* If the
* className is not listed as one that is to be renamed, the returned
* string == className, if the className is registered to be renamed
* than the className != returned value, even in a case when className.equals (retValue)
- * <p/>
+ * <p>
* Similar behaviour applies to <b>filenames</b> provided by layers (system filesystem). Filenames
* can be also translated to adapt to location changes e.g. in action registrations. Note that
* <b>no spaces or special characters</b> are allowed in both translated filenames or translation
* results. Filenames must conform to regexp {@code ^[/a-zA-Z0-9$_.+-]+$}. Keys and values are treated
* as paths from fs root.
*
- * <p/>
+ * <p>
* Example of file path translation (action registration file has moved):
* <pre>
* # registration ID has changed
@@ -1560,7 +1564,7 @@ widthcheck: {
* and {@link URI#resolve(URI)}.
* @param f a file
* @return a {@code file}-protocol URI which may use the host field
- * @see java.nio.file.Path.toUri
+ * @see java.nio.file.Path#toUri()
* @since 8.25
*/
public static URI toURI(File f) {
diff --git a/platform/openide.util/src/org/openide/util/EditableProperties.java b/platform/openide.util/src/org/openide/util/EditableProperties.java
index 1e5b177be7..1fef573fab 100644
--- a/platform/openide.util/src/org/openide/util/EditableProperties.java
+++ b/platform/openide.util/src/org/openide/util/EditableProperties.java
@@ -47,7 +47,7 @@ import java.util.Set;
/**
* Similar to {@link java.util.Properties} but designed to retain additional
* information needed for safe hand-editing.
- * Useful for various <samp>*.properties</samp> in a project:
+ * Useful for various <code>*.properties</code> in a project:
* <ol>
* <li>Can associate comments with particular entries.
* <li>Order of entries preserved during modifications whenever possible.
@@ -260,7 +260,7 @@ public final class EditableProperties extends AbstractMap<String,String> impleme
* Same behavior as {@link #setProperty(String,String)} with the difference that each item
* will be stored on its own line of text. {@link #getProperty} will simply concatenate
* all the items into one string, so generally separators
- * (such as <samp>:</samp> for path-like properties) must be included in
+ * (such as <code>:</code> for path-like properties) must be included in
* the items (for example, at the end of all but the last item).
* @param key a property name; cannot be null nor empty
* @param value the desired value; cannot be null; can be empty array
diff --git a/platform/openide.util/src/org/openide/util/Enumerations.java b/platform/openide.util/src/org/openide/util/Enumerations.java
index 87c8fd36a9..9f33fde620 100644
--- a/platform/openide.util/src/org/openide/util/Enumerations.java
+++ b/platform/openide.util/src/org/openide/util/Enumerations.java
@@ -49,6 +49,7 @@ public final class Enumerations extends Object {
* Always returns <code>false</code> from
* <code>empty().hasMoreElements()</code> and throws <code>NoSuchElementException</code>
* from <code>empty().nextElement()</code>.
+ * @param <T> type of initial content
* @return the enumeration
*/
public static final <T> Enumeration<T> empty() {
@@ -58,6 +59,7 @@ public final class Enumerations extends Object {
/**
* Creates an enumeration with one element.
+ * @param <T> type of initial content
* @param obj the element to be present in the enumeration.
* @return enumeration
*/
@@ -71,7 +73,7 @@ public final class Enumerations extends Object {
* end of <code>en1</code> is reached its elements are being served.
* As soon as the <code>en1</code> has no more elements, the content
* of <code>en2</code> is being returned.
- *
+ * @param <T> type of initial content
* @param en1 first enumeration
* @param en2 second enumeration
* @return enumeration
@@ -90,7 +92,7 @@ public final class Enumerations extends Object {
* all their content. Each of the provided enumeration is fully read
* and their content returned before the next enumeration is asked for
* their elements.
- *
+ * @param <T> type of initial content
* @param enumOfEnums Enumeration of Enumeration elements
* @return enumeration
*/
@@ -103,7 +105,7 @@ public final class Enumerations extends Object {
* each of the provided elements just once.
* The elements are compared
* using their default <code>equals</code> and <code>hashCode</code> methods.
- *
+ * @param <T> type of initial content
* @param en enumeration to filter
* @return enumeration without duplicated items
*/
@@ -121,6 +123,7 @@ public final class Enumerations extends Object {
/**
* Returns an enumeration that iterates over provided array.
+ * @param <T> type of initial content
* @param arr the array of object
* @return enumeration of those objects
*/
@@ -130,6 +133,7 @@ public final class Enumerations extends Object {
/**
* Removes all <code>null</code>s from the input enumeration.
+ * @param <T> type of initial content
* @param en enumeration that can contain nulls
* @return new enumeration without null values
*/
@@ -151,7 +155,8 @@ public final class Enumerations extends Object {
* };
* Enumeration strings = Enumerations.convert(elems, convertToString);
* </pre>
- *
+ * @param <T> type of initial content
+ * @param <R> type of result content
* @param en enumeration of any objects
* @param processor a callback processor for the elements (its toAdd arguments is always null)
* @return new enumeration where all elements has been processed
@@ -179,7 +184,8 @@ public final class Enumerations extends Object {
* };
* Enumeration strings = Enumerations.filter(elems, onlyString);
* </pre>
- *
+ * @param <T> type of initial content
+ * @param <R> type of result content
* @param en enumeration of any objects
* @param filter a callback processor for the elements (its toAdd arguments is always null)
* @return new enumeration which does not include non-processed (returned null from processor) elements
@@ -196,7 +202,7 @@ public final class Enumerations extends Object {
* Before any element is returned
* for the resulting enumeration it is processed in the {@link Processor} and
* the processor is allowed to modify it and also add additional elements
- * at the (current) end of the <q>queue</q> by calling <code>toAdd.add</code>
+ * at the (current) end of the <code>queue</code> by calling <code>toAdd.add</code>
* or <code>toAdd.addAll</code>. No other methods can be called on the
* provided <code>toAdd</code> collection.
* <p>
@@ -211,7 +217,8 @@ public final class Enumerations extends Object {
* };
* Enumeration strings = Enumerations.queue(elems, queueSubnodes);
* </pre>
- *
+ * @param <T> type of initial content
+ * @param <R> type of result content
* @param en initial content of the resulting enumeration
* @param filter the processor that is called for each element and can
* add and addAll elements to its toAdd Collection argument and
diff --git a/platform/openide.util/src/org/openide/util/Exceptions.java b/platform/openide.util/src/org/openide/util/Exceptions.java
index aacff609e8..d3959ecb28 100644
--- a/platform/openide.util/src/org/openide/util/Exceptions.java
+++ b/platform/openide.util/src/org/openide/util/Exceptions.java
@@ -51,7 +51,7 @@ public final class Exceptions extends Object {
/** Attaches additional message to given exception. This message will
* be visible when one does <code>e.printStackTrace()</code>.
- *
+ * @param <E> type of excetion
* @param e exception to annotate
* @param msg the message to add to the exception
* @return the exception <code>e</code>
@@ -65,7 +65,7 @@ public final class Exceptions extends Object {
/** Attaches additional localized message to given exception. This message
* can be extracted later by using {@link #findLocalizedMessage}.
- *
+ * @param <E> type of excetion
* @param e exception to annotate
* @param localizedMessage the localized message to add to the exception
* @return the exception <code>e</code>
@@ -97,9 +97,10 @@ public final class Exceptions extends Object {
* then used as a level for reported {@link LogRecord}. This allows
* those who report exceptions to annotate them as unimportant,
* expected.
- *
+ * @param <E> type of excetion
* @param e exception to assign severity to
* @param severity the severity
+ * @return the exception <code>e</code>
* @since 8.8
*/
public static <E extends Throwable> E attachSeverity(E e, Level severity) {
diff --git a/platform/openide.util/src/org/openide/util/MapFormat.java b/platform/openide.util/src/org/openide/util/MapFormat.java
index 2080eebc85..056bd674b5 100644
--- a/platform/openide.util/src/org/openide/util/MapFormat.java
+++ b/platform/openide.util/src/org/openide/util/MapFormat.java
@@ -135,7 +135,7 @@ public class MapFormat extends Format {
}
*/
/** Returns the value for given key. Subclass may define its own beahvior of
- * this method. For example, if key is not defined, subclass can return <not defined>
+ * this method. For example, if key is not defined, subclass can return <not defined>
* string.
*
* @param key Key.
@@ -151,6 +151,7 @@ public class MapFormat extends Format {
* @exception IllegalArgumentException if number of arguments exceeds BUFSIZE or
* parser found unmatched brackets (this exception should be switched off
* using setExactMatch(false)).
+ * @return parsed string
*/
public String processPattern(String newPattern) throws IllegalArgumentException {
int idx = 0;
@@ -306,6 +307,7 @@ public class MapFormat extends Format {
/**
* Parses the string. Does not yet handle recursion (where
* the substituted strings contain {n} references.)
+ * @param source string to parse
* @return New format.
*/
public String parse(String source) {
@@ -339,6 +341,7 @@ public class MapFormat extends Format {
/** Test whether formatter will throw exception if object for key was not found.
* If given map does not contain object for key specified, it could
* throw an exception. Returns true if throws. If not, key is left unchanged.
+ * @return true if throws.
*/
public boolean willThrowExceptionIfKeyWasNotFound() {
return throwex;
@@ -356,6 +359,7 @@ public class MapFormat extends Format {
/** Test whether both brackets are required in the expression.
* If not, use setExactMatch(false) and formatter will ignore missing right
* bracket. Advanced feature.
+ * @return true if both brackets are required
*/
public boolean isExactMatch() {
return exactmatch;
@@ -370,7 +374,9 @@ public class MapFormat extends Format {
exactmatch = flag;
}
- /** Returns string used as left brace */
+ /** Returns string used as left brace.
+ * @return string used as left brace
+ */
public String getLeftBrace() {
return ldel;
}
@@ -382,7 +388,9 @@ public class MapFormat extends Format {
ldel = delimiter;
}
- /** Returns string used as right brace */
+ /** Returns string used as right brace.
+ * @return string used as right brace
+ */
public String getRightBrace() {
return rdel;
}
@@ -394,7 +402,9 @@ public class MapFormat extends Format {
rdel = delimiter;
}
- /** Returns argument map */
+ /** Returns argument map.
+ * @return argument map
+ */
public Map getMap() {
return argmap;
}
diff --git a/platform/openide.util/src/org/openide/util/Mutex.java b/platform/openide.util/src/org/openide/util/Mutex.java
index 1581c5a673..69045fd7e9 100644
--- a/platform/openide.util/src/org/openide/util/Mutex.java
+++ b/platform/openide.util/src/org/openide/util/Mutex.java
@@ -52,7 +52,7 @@ import org.openide.util.spi.MutexImplementation;
* Mutex m = new Mutex();
*
* // Grant write access, compute an integer and return it:
-* return m.writeAccess(new Mutex.Action<Integer>(){
+* return m.writeAccess(new Mutex.Action<Integer>(){
* public Integer run() {
* return 1;
* }
@@ -61,7 +61,7 @@ import org.openide.util.spi.MutexImplementation;
* // Obtain read access, do some computation,
* // possibly throw an IOException:
* try {
-* m.readAccess(new Mutex.ExceptionAction<Void>() {
+* m.readAccess(new Mutex.ExceptionAction<Void>() {
* public Void run() throws IOException {
* if (...) throw new IOException();
* return null;
@@ -183,7 +183,6 @@ public final class Mutex {
* @param privileged can enter privileged states of this Mutex
* @param executor allows to wrap the work of the mutex with a custom code
* @since 7.12
- * @see SimpleMutex#SimpleMutex(org.openide.util.ReadWriteAccess.Privileged, java.util.concurrent.Executor)
*/
public Mutex(Privileged privileged, Executor executor) {
this.impl = DefaultMutexImplementation.controlledBy(privileged.delegate, executor);
@@ -191,6 +190,7 @@ public final class Mutex {
/** Run an action only with read access.
* See class description re. entering for write access within the dynamic scope.
+ * @param <T> type of action
* @param action the action to perform
* @return the object returned from {@link Mutex.Action#run}
*/
@@ -208,7 +208,7 @@ public final class Mutex {
* in a <code>MutexException</code> and thrown from this method. One is encouraged
* to catch <code>MutexException</code>, obtain the inner exception, and rethrow it.
* Here is an example:
- * <p><code><PRE>
+ * <PRE><code>
* try {
* mutex.readAccess (new ExceptionAction () {
* public void run () throws IOException {
@@ -218,9 +218,10 @@ public final class Mutex {
* } catch (MutexException ex) {
* throw (IOException) ex.getException ();
* }
- * </PRE></code>
+ * </code></PRE>
* Note that <em>runtime exceptions</em> are always passed through, and neither
* require this invocation style, nor are encapsulated.
+ * @param <T> type of action
* @param action the action to execute
* @return the object returned from {@link Mutex.ExceptionAction#run}
* @exception MutexException encapsulates a user exception
@@ -243,7 +244,7 @@ public final class Mutex {
/** Run an action with write access.
* The same thread may meanwhile reenter the mutex; see the class description for details.
- *
+ * @param <T> type of action
* @param action the action to perform
* @return the result of {@link Mutex.Action#run}
*/
@@ -257,7 +258,7 @@ public final class Mutex {
/** Run an action with write access and possibly throw an exception.
* Here is an example:
- * <p><code><PRE>
+ * <PRE><code>
* try {
* mutex.writeAccess (new ExceptionAction () {
* public void run () throws IOException {
@@ -267,8 +268,8 @@ public final class Mutex {
* } catch (MutexException ex) {
* throw (IOException) ex.getException ();
* }
- * </PRE></code>
- *
+ * </code></PRE>
+ * @param <T> type of action
* @param action the action to execute
* @return the result of {@link Mutex.ExceptionAction#run}
* @exception MutexException an encapsulated checked exception, if any
@@ -370,7 +371,7 @@ public final class Mutex {
}
/** Action to be executed in a mutex without throwing any checked exceptions.
* Unchecked exceptions will be propagated to calling code.
- * @param T the type of object to return
+ * @param <T> the type of object to return
*/
@SuppressWarnings("PublicInnerClass")
public interface Action<T> extends ExceptionAction<T> {
@@ -386,7 +387,7 @@ public final class Mutex {
* code should catch the encapsulating exception and rethrow the
* real one.
* Unchecked exceptions will be propagated to calling code without encapsulation.
- * @param T the type of object to return
+ * @param <T> the type of object to return
*/
@SuppressWarnings("PublicInnerClass")
public interface ExceptionAction<T> {
diff --git a/platform/openide.util/src/org/openide/util/MutexException.java b/platform/openide.util/src/org/openide/util/MutexException.java
index 6f93508939..f8219ffe87 100644
--- a/platform/openide.util/src/org/openide/util/MutexException.java
+++ b/platform/openide.util/src/org/openide/util/MutexException.java
@@ -21,9 +21,9 @@ package org.openide.util;
/** Encapsulates other exceptions thrown from a mutex method.
*
-* @see ReadWriteAccess.ExceptionAction
-* @see ReadWriteAccess#readAccess(ReadWriteAccess.ExceptionAction)
-* @see ReadWriteAccess#writeAccess(ReadWriteAccess.ExceptionAction)
+* @see Mutex.ExceptionAction
+* @see Mutex#readAccess(Mutex.ExceptionAction)
+* @see Mutex#writeAccess(Mutex.ExceptionAction)
*
* @author Jaroslav Tulach
*/
diff --git a/platform/openide.util/src/org/openide/util/NbBundle.java b/platform/openide.util/src/org/openide/util/NbBundle.java
index 982c4fed44..cc659e4f35 100644
--- a/platform/openide.util/src/org/openide/util/NbBundle.java
+++ b/platform/openide.util/src/org/openide/util/NbBundle.java
@@ -138,8 +138,8 @@ public class NbBundle extends Object {
* @return URL of matching localized file
* @throws MissingResourceException if not found
* @deprecated Use the <code>nbresloc</code> URL protocol instead. This method does a poor
- * job of handling resources such as <samp>/some.dir/res.txt</samp> or
- * <samp>/some/res.txt.sample</samp>.
+ * job of handling resources such as <code>/some.dir/res.txt</code> or
+ * <code>/some/res.txt.sample</code>.
*/
@Deprecated
public static synchronized URL getLocalizedFile(String baseName, String ext)
@@ -155,8 +155,8 @@ public class NbBundle extends Object {
* @return URL of matching localized file
* @throws MissingResourceException if not found
* @deprecated Use the <code>nbresloc</code> URL protocol instead. This method does a poor
- * job of handling resources such as <samp>/some.dir/res.txt</samp> or
- * <samp>/some/res.txt.sample</samp>.
+ * job of handling resources such as <code>/some.dir/res.txt</code> or
+ * <code>/some/res.txt.sample</code>.
*/
@Deprecated
public static synchronized URL getLocalizedFile(String baseName, String ext, Locale locale)
@@ -173,8 +173,8 @@ public class NbBundle extends Object {
* @return URL of matching localized file
* @throws MissingResourceException if not found
* @deprecated Use the <code>nbresloc</code> URL protocol instead. This method does a poor
- * job of handling resources such as <samp>/some.dir/res.txt</samp> or
- * <samp>/some/res.txt.sample</samp>.
+ * job of handling resources such as <code>/some.dir/res.txt</code> or
+ * <code>/some/res.txt.sample</code>.
*/
@Deprecated
public static synchronized URL getLocalizedFile(String baseName, String ext, Locale locale, ClassLoader loader)
@@ -270,16 +270,16 @@ public class NbBundle extends Object {
* Find a localized and/or branded value for a given key and locale.
* Scans through a map to find
* the most localized match possible. For example:
- * <p><code><PRE>
+ * <p><code>
* findLocalizedValue (hashTable, "keyName", new Locale ("cs_CZ"))
- * </PRE></code>
+ * </code>
* <p>This would return the first non-<code>null</code> value obtained from the following tests:
* <UL>
* <LI> <CODE>hashTable.get ("keyName_cs_CZ")</CODE>
* <LI> <CODE>hashTable.get ("keyName_cs")</CODE>
* <LI> <CODE>hashTable.get ("keyName")</CODE>
* </UL>
- *
+ * @param <T> type of returned object
* @param table mapping from localized strings to objects
* @param key the key to look for
* @param locale the locale to use
@@ -308,7 +308,7 @@ public class NbBundle extends Object {
/**
* Find a localized and/or branded value for a given key in the default system locale.
- *
+ * @param <T> type of returned object
* @param table mapping from localized strings to objects
* @param key the key to look for
* @return the localized object or <code>null</code> if no key matches
@@ -452,8 +452,8 @@ public class NbBundle extends Object {
* Get a resource bundle by name.
* Like {@link ResourceBundle#getBundle(String,Locale,ClassLoader)} but faster,
* and also understands branding.
- * First looks for <samp>.properties</samp>-based bundles, then <samp>.class</samp>-based.
- * @param name the base name of the bundle, e.g. <samp>org.netbeans.modules.foo.Bundle</samp>
+ * First looks for <code>.properties</code>-based bundles, then <code>.class</code>-based.
+ * @param name the base name of the bundle, e.g. <code>org.netbeans.modules.foo.Bundle</code>
* @param locale the locale to use
* @param loader a class loader to search in
* @return a resource bundle (locale- and branding-merged), or null if not found
@@ -520,7 +520,7 @@ public class NbBundle extends Object {
/**
* Load a resource bundle (without caching).
- * @param name the base name of the bundle, e.g. <samp>org.netbeans.modules.foo.Bundle</samp>
+ * @param name the base name of the bundle, e.g. <code>org.netbeans.modules.foo.Bundle</code>
* @param locale the locale to use
* @param loader a class loader to search in
* @return a resource bundle (locale- and branding-merged), or null if not found
@@ -581,8 +581,8 @@ public class NbBundle extends Object {
/**
* Load a class-based resource bundle.
- * @param name the base name of the bundle, e.g. <samp>org.netbeans.modules.foo.Bundle</samp>
- * @param sname the name with slashes, e.g. <samp>org/netbeans/modules/foo/Bundle</samp>
+ * @param name the base name of the bundle, e.g. <code>org.netbeans.modules.foo.Bundle</code>
+ * @param sname the name with slashes, e.g. <code>org/netbeans/modules/foo/Bundle</code>
* @param locale the locale to use
* @param suffixes a list of suffixes to apply to the bundle name, in <em>increasing</em> order of specificity
* @param loader a class loader to search in
@@ -748,10 +748,10 @@ public class NbBundle extends Object {
* For example, when {@link #getBranding} returns <code>branding</code>
* and the default locale is German, you might get a sequence such as:
* <ol>
- * <li><samp>"_branding_de"</samp>
- * <li><samp>"_branding"</samp>
- * <li><samp>"_de"</samp>
- * <li><samp>""</samp>
+ * <li><code>"_branding_de"</code></li>
+ * <li><code>"_branding"</code></li>
+ * <li><code>"_de"</code></li>
+ * <li><code>""</code></li>
* </ol>
* @return a read-only iterator of type <code>String</code>
* @since 1.1.5
@@ -828,6 +828,7 @@ public class NbBundle extends Object {
* Values containing <code>{0}</code> etc. are assumed to be message formats and so may need escapes for metacharacters such as {@code '}.
* A line may also be a comment if it starts with {@code #}, which may be useful for translators;
* it is recommended to use the format {@code # {0} - summary of param}.
+ * @return list of key/value
*/
String[] value();
}
@@ -876,7 +877,7 @@ public class NbBundle extends Object {
}
/**
- * A resource bundle based on <samp>.properties</samp> files (or any map).
+ * A resource bundle based on <code>.properties</code> files (or any map).
*/
private static final class PBundle extends ResourceBundle {
private final Map<String,String> m;
diff --git a/platform/openide.util/src/org/openide/util/NbCollections.java b/platform/openide.util/src/org/openide/util/NbCollections.java
index 35ad347fa1..7296258782 100644
--- a/platform/openide.util/src/org/openide/util/NbCollections.java
+++ b/platform/openide.util/src/org/openide/util/NbCollections.java
@@ -55,6 +55,7 @@ public class NbCollections {
/**
* Create a typesafe copy of a raw set.
+ * @param <E> desired type of the entry
* @param rawSet an unchecked set
* @param type the desired supertype of the entries
* @param strict true to throw a <code>ClassCastException</code> if the raw set has an invalid entry,
@@ -83,6 +84,7 @@ public class NbCollections {
/**
* Create a typesafe copy of a raw list.
+ * @param <E> desired type of the entry
* @param rawList an unchecked list
* @param type the desired supertype of the entries
* @param strict true to throw a <code>ClassCastException</code> if the raw list has an invalid entry,
@@ -111,6 +113,8 @@ public class NbCollections {
/**
* Create a typesafe copy of a raw map.
+ * @param <K> type of key
+ * @param <V> type of value
* @param rawMap an unchecked map
* @param keyType the desired supertype of the keys
* @param valueType the desired supertype of the values
@@ -185,6 +189,7 @@ public class NbCollections {
/**
* Create a typesafe filter of an unchecked iterator.
* {@link Iterator#remove} will work if it does in the unchecked iterator.
+ * @param <E> type of element
* @param rawIterator an unchecked iterator
* @param type the desired enumeration type
* @param strict if false, elements which are not null but not assignable to the requested type are omitted;
@@ -215,6 +220,7 @@ public class NbCollections {
* {@link Set#contains} also performs a type check and will throw {@link ClassCastException}
* for an illegal argument.
* The view is serializable if the underlying set is.
+ * @param <E> type of element
* @param rawSet an unchecked set
* @param type the desired element type
* @param strict if false, elements in the underlying set which are not null and which are not assignable
@@ -294,6 +300,8 @@ public class NbCollections {
* {@link Map#get}, {@link Map#containsKey}, and {@link Map#containsValue} also perform a type check
* and will throw {@link ClassCastException} for an illegal argument.
* The view is serializable if the underlying map is.
+ * @param <K> type of key
+ * @param <V> type of value
* @param rawMap an unchecked map
* @param keyType the desired entry key type
* @param valueType the desired entry value type
@@ -445,6 +453,7 @@ public class NbCollections {
/**
* Create a typesafe filter of an unchecked enumeration.
+ * @param <E> type of element
* @param rawEnum an unchecked enumeration
* @param type the desired enumeration type
* @param strict if false, elements which are not null but not assignable to the requested type are omitted;
@@ -486,6 +495,7 @@ public class NbCollections {
* }
* </pre>
* </div>
+ * @param <E> type of element
* @param iterator an iterator
* @return an iterable wrapper which will traverse the iterator once
* @throws NullPointerException if the iterator is null
@@ -519,6 +529,7 @@ public class NbCollections {
* }
* </pre>
* </div>
+ * @param <E> type of element
* @param enumeration an enumeration
* @return an iterable wrapper which will traverse the enumeration once
* ({@link Iterator#remove} is not supported)
diff --git a/platform/openide.util/src/org/openide/util/RequestProcessor.java b/platform/openide.util/src/org/openide/util/RequestProcessor.java
index 7e79619d19..f98d367e7e 100644
--- a/platform/openide.util/src/org/openide/util/RequestProcessor.java
+++ b/platform/openide.util/src/org/openide/util/RequestProcessor.java
@@ -61,9 +61,9 @@ import org.openide.util.lookup.Lookups;
* <A name="use_cases">There are several use cases for RequestProcessor</A>,
* most of them start with creating own <code>RequestProcessor</code>
* instance (which by itself is quite lightweight).
- *
- * <h5>Do something later</h5>
- *
+ * <p>
+ * <strong>Do something later</strong>
+ * <p>
* In case you want something to be done later in some background thread,
* create an instance of <code>RequestProcessor</code> and post tasks to it.
* <pre>
@@ -94,9 +94,9 @@ import org.openide.util.lookup.Lookups;
* // later wait
* last.{@link RequestProcessor.Task#waitFinished waitFinished()}
* </pre>
- *
- * <h5>Periodic task</h5>
- *
+ * <p>
+ * <strong>Periodic task</strong>
+ * <p>
* It is also possible to do something periodically. Use the {@link RequestProcessor.Task#schedule schedule} method:
* <pre>
* class Periodic implements Runnable {
@@ -112,9 +112,9 @@ import org.openide.util.lookup.Lookups;
* background activity. It is generally considered evil if some code runs
* without any user action. Your code shall respect the application's state,
* and for example when the application is minimized, do nothing.
- *
- * <h5>Sliding task</h5>
- *
+ * <p>
+ * <strong>Sliding task</strong>
+ * <p>
* Often you want to perform an update of your object internals
* based on changes in some model. However your update may be costly
* and you want to do it just once, regardless of how many changes are
@@ -136,9 +136,9 @@ import org.openide.util.lookup.Lookups;
* The above code coalesces all events that arrive in 1s and for all of them
* does <code>doTheWork</code> just once.
*
- *
- * <h5>Interruption of tasks</h5>
- *
+ * <p>
+ * <strong>Interruption of tasks</strong>
+ * <p>
* Since version 6.3 there is a conditional support for interruption of long running tasks.
* There always was a way to cancel not yet running task using {@link RequestProcessor.Task#cancel }
* but if the task's run() method was already running, one was out of luck.
@@ -157,7 +157,7 @@ import org.openide.util.lookup.Lookups;
* }
* }
* </pre>
- * <p/>
+ * <p>
* Since <code>org.openide.util</code>, implements
* {@link java.util.concurrent.ScheduledExecutorService}
* @author Petr Nejedly, Jaroslav Tulach, Tim Boudreau
@@ -506,7 +506,7 @@ public final class RequestProcessor implements ScheduledExecutorService {
*
* @deprecated Sharing of one singlethreaded <CODE>RequestProcessor</CODE>
* among different users and posting even blocking requests is inherently
- * deadlock-prone. See <A href="#use_cases">use cases</A>. */
+ * deadlock-prone. See {@link RequestProcessor use cases}. */
@Deprecated
public static Task postRequest(Runnable run) {
return DEFAULT.post(run);
@@ -522,7 +522,7 @@ public final class RequestProcessor implements ScheduledExecutorService {
*
* @deprecated Sharing of one singlethreaded <CODE>RequestProcessor</CODE>
* among different users and posting even blocking requests is inherently
- * deadlock-prone. See <A href="#use_cases">use cases</A>. */
+ * deadlock-prone. See {@link RequestProcessor use cases}. */
@Deprecated
public static Task postRequest(final Runnable run, int timeToWait) {
return DEFAULT.post(run, timeToWait);
@@ -538,7 +538,7 @@ public final class RequestProcessor implements ScheduledExecutorService {
*
* @deprecated Sharing of one singlethreaded <CODE>RequestProcessor</CODE>
* among different users and posting even blocking requests is inherently
- * deadlock-prone. See <A href="#use_cases">use cases</A>. */
+ * deadlock-prone. See {@link RequestProcessor use cases}. */
@Deprecated
public static Task postRequest(final Runnable run, int timeToWait, int priority) {
return DEFAULT.post(run, timeToWait, priority);
@@ -552,7 +552,7 @@ public final class RequestProcessor implements ScheduledExecutorService {
*
* @deprecated Sharing of one singlethreaded <CODE>RequestProcessor</CODE>
* among different users and posting even blocking requests is inherently
- * deadlock-prone. See <A href="#use_cases">use cases</A>. */
+ * deadlock-prone. See {@link RequestProcessor use cases}. */
@Deprecated
public static Task createRequest(Runnable run) {
return DEFAULT.create(run);
@@ -642,7 +642,7 @@ public final class RequestProcessor implements ScheduledExecutorService {
/**
* {@inheritDoc}
- * @throws an IllegalStateException if called on the
+ * @throws IllegalStateException if called on the
* {@linkplain #getDefault default request processor}
* @since org.openide.util 8.2
*/
@@ -658,7 +658,7 @@ public final class RequestProcessor implements ScheduledExecutorService {
/**
* {@inheritDoc}
- * @throws an IllegalStateException if called on the
+ * @throws IllegalStateException if called on the
* {@linkplain #getDefault default request processor}
* @since org.openide.util 8.2
*/
@@ -759,7 +759,7 @@ outer: do {
/**
* {@inheritDoc}
- * <p/>
+ * <p>
* <b>Note:</b> If the passed {@link java.util.concurrent.Callable} implements
* {@link org.openide.util.Cancellable}, then that object's {@link org.openide.util.Cancellable#cancel()}
* method will be called if {@link java.util.concurrent.Future#cancel(boolean)} is invoked.
@@ -805,7 +805,7 @@ outer: do {
/**
* {@inheritDoc}
- * <p/>
+ * <p>
* <b>Note:</b> If the passed {@link java.lang.Runnable} implements
* {@link org.openide.util.Cancellable}, then that object's {@link org.openide.util.Cancellable#cancel()}
* method will be called if {@link java.util.concurrent.Future#cancel(boolean)} is invoked.
@@ -841,7 +841,7 @@ outer: do {
/**
* {@inheritDoc}
- * <p/>
+ * <p>
* Executes the given tasks, returning a list of Futures holding their
* status and results when all complete or the timeout expires, whichever
* happens first.
@@ -870,7 +870,7 @@ outer: do {
}
/**
* {@inheritDoc}
- * <p/>
+ * <p>
* Executes the given tasks, returning the result of one which has
* completed and cancelling any incomplete tasks.
* @since org.openide.util 8.2
@@ -901,7 +901,7 @@ outer: do {
}
/**
* {@inheritDoc}
- * <p/>
+ * <p>
* Executes the given tasks, returning a list of Futures holding their
* status and results when all complete or the timeout expires, whichever
* happens first.
@@ -985,7 +985,7 @@ outer: do {
/**
* {@inheritDoc}
- * <p/>
+ * <p>
* Schedules a runnable which will run with a given frequency, regardless
* of how long execution takes, with the exception that if execution takes
* longer than the specified delay, execution will be delayed but will
@@ -999,7 +999,7 @@ outer: do {
/**
* {@inheritDoc}
- * <p/>
+ * <p>
* Schedules a runnable which will run repeatedly after the specified initial
* delay, with the specified delay between the completion of one run and
* the start of the next.
diff --git a/platform/openide.util/src/org/openide/util/Task.java b/platform/openide.util/src/org/openide/util/Task.java
index 817299112a..e5adea2695 100644
--- a/platform/openide.util/src/org/openide/util/Task.java
+++ b/platform/openide.util/src/org/openide/util/Task.java
@@ -30,7 +30,7 @@ import java.util.logging.Logger;
* to finish.
* <P>
* For example:
-* <p><code><PRE>
+* <PRE><code>
* Runnable r = new Runnable () {
* public void run () {
* // do something
@@ -38,7 +38,7 @@ import java.util.logging.Logger;
* };
* Task task = new Task (r);
* RequestProcessor.postRequest (task);
-* </PRE></code>
+* </code></PRE>
* <p>In a different thread one can then test <CODE>task.isFinished ()</CODE>
* or wait for it with <CODE>task.waitFinished ()</CODE>.
*
@@ -193,7 +193,7 @@ public class Task extends Object implements Runnable {
}
/** Notify all waiters that this task has finished.
- * @see #run
+ * @see #run()
*/
protected final void notifyFinished() {
Iterator<TaskListener> it;
diff --git a/platform/openide.util/src/org/openide/util/TopologicalSortException.java b/platform/openide.util/src/org/openide/util/TopologicalSortException.java
index 7f64f30cc2..146d5a25f5 100644
--- a/platform/openide.util/src/org/openide/util/TopologicalSortException.java
+++ b/platform/openide.util/src/org/openide/util/TopologicalSortException.java
@@ -29,7 +29,7 @@ import java.util.*;
*
* @author Jaroslav Tulach
* @since 3.30
-* @see BaseMutexUtilities#topologicalSort
+* @see Utilities#topologicalSort
*/
public final class TopologicalSortException extends Exception {
/** all vertexes */
diff --git a/platform/openide.util/src/org/openide/util/URLStreamHandlerRegistration.java b/platform/openide.util/src/org/openide/util/URLStreamHandlerRegistration.java
index 425b9d59b9..bb3778c133 100644
--- a/platform/openide.util/src/org/openide/util/URLStreamHandlerRegistration.java
+++ b/platform/openide.util/src/org/openide/util/URLStreamHandlerRegistration.java
@@ -48,12 +48,14 @@ public @interface URLStreamHandlerRegistration {
/**
* URL protocol(s) which are handled.
* {@link URLStreamHandler#openConnection} will be called with a matching {@link URL#getProtocol}.
+ * @return list of protocol which are handled
*/
String[] protocol();
/**
* An optional position in which to register this handler relative to others.
* The lowest-numbered handler is used in favor of any others, including unnumbered handlers.
+ * @return position to register this handler
*/
int position() default Integer.MAX_VALUE;
diff --git a/platform/openide.util/src/org/openide/util/Union2.java b/platform/openide.util/src/org/openide/util/Union2.java
index e6a27853aa..059e86c657 100644
--- a/platform/openide.util/src/org/openide/util/Union2.java
+++ b/platform/openide.util/src/org/openide/util/Union2.java
@@ -67,6 +67,8 @@ public abstract class Union2<First,Second> implements Cloneable, Serializable {
/**
* Construct a union based on the first type.
+ * @param <First> type of first type
+ * @param <Second> type of second type
* @param first an object of the first type
* @return a union containing that object
*/
@@ -76,6 +78,8 @@ public abstract class Union2<First,Second> implements Cloneable, Serializable {
/**
* Construct a union based on the second type.
+ * @param <First> type of first type
+ * @param <Second> type of second type
* @param second an object of the second type
* @return a union containing that object
*/
diff --git a/platform/openide.util/src/org/openide/util/WeakListeners.java b/platform/openide.util/src/org/openide/util/WeakListeners.java
index b39e858d45..22baf46641 100644
--- a/platform/openide.util/src/org/openide/util/WeakListeners.java
+++ b/platform/openide.util/src/org/openide/util/WeakListeners.java
@@ -40,8 +40,9 @@ import javax.swing.event.DocumentListener;
* The examples are written for ChangeListener. The <code>Utilities</code>
* have factory methods for the most common listeners used in NetBeans
* and also one universal factory method you can use for other listeners.
- *
- * <H2>How to use it:</H2>
+ * <p>
+ * <strong>How to use it:</strong>
+ * <p>
* Here is an example how to write a listener/observer and make it listen
* on some source:
* <pre>
@@ -95,8 +96,9 @@ import javax.swing.event.DocumentListener;
* }
* }
* </pre>
- *
- * <H2>How to <font color=red>not</font> use it:</H2>
+ * <p>
+ * <strong>How to <span style="color:red">not</span> use it:</strong>
+ * <p>
* Here are examples of a common mistakes done when using <em>weak listener</em>:
* <pre>
* public class Observer {
@@ -127,8 +129,8 @@ import javax.swing.event.DocumentListener;
* </pre>
* Mistake: The weak listener is unable to unregister itself from the source
* once the listener is freed. For explanation, read below.
- *
- <H2>How does it work:</H2>
+ * <p>
+ * <strong>How does it work:</strong>
* <P>The <em>weak listener</em> is used as a reference-weakening wrapper
* around the listener. It is itself strongly referenced from the implementation
* of the source (e.g. from its <code>EventListenerList</code>) but it references
@@ -177,7 +179,7 @@ public final class WeakListeners {
/** Generic factory method to create weak listener for any listener
* interface.
- *
+ * @param <T> type of listener
* @param lType the type of listener to create. It can be any interface,
* but only interfaces are allowed.
* @param l the listener to delegate to, <CODE>l</CODE> must be an instance
@@ -217,7 +219,7 @@ public final class WeakListeners {
* This will correctly create <code>ObjectChangeListener</code>
* and unregister it by
* calling <code>removeNamingListener</code>.
- *
+ * @param <T> type of listener
* @param lType the type the listener shall implement. It can be any interface,
* but only interfaces are allowed.
* @param apiType the interface the returned object will be used as. It
diff --git a/platform/openide.util/src/org/openide/util/doc-files/api.html b/platform/openide.util/src/org/openide/util/doc-files/api.html
index a4ad17271e..0c41517c6d 100644
--- a/platform/openide.util/src/org/openide/util/doc-files/api.html
+++ b/platform/openide.util/src/org/openide/util/doc-files/api.html
@@ -122,7 +122,7 @@ manually retrieve sets of instances as a client, which is not used
very frequently in new code but helps to understand what lookup is
doing behind the scenes. Then lookup itself is discussed, and how the
standard instance lookup works and how it relates to JDK's
-<a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider">
+<a href="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Service%20Provider">
standard for service provider registration</a>.
Lookup templates, which separate the
provision of instances from the provision of categories, will be
@@ -418,7 +418,7 @@ impl.useIt();
Such implementation has to be registered by some module to the system.
Either via layer as described above or as a JDK's
-<a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider">
+<a href="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Service%20Provider">
service provider</a>. If some module wants to register for example
<span class="type">org.me.MyService</span> it shall provide file name
<span class="function-name">META-INF/services/org.me.MyService</span> in its own JAR
@@ -432,7 +432,7 @@ to answer the query in the above example.
<div class="nonnormative">
The Lookup supports two small extensions to the
- <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider">JDK's
+ <a href="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Service%20Provider">JDK's
standard</a>. It allows a module to remove class registered by
another one. That is why it is possible to write a module that
disables the <span class="type">org.you.MyServiceImpl</span> implementation
diff --git a/platform/openide.util/src/org/openide/util/doc-files/preferences.html b/platform/openide.util/src/org/openide/util/doc-files/preferences.html
index 1b0b4c7730..b5733030f3 100644
--- a/platform/openide.util/src/org/openide/util/doc-files/preferences.html
+++ b/platform/openide.util/src/org/openide/util/doc-files/preferences.html
@@ -26,7 +26,7 @@
</head>
<body>
<h1 align="left">Preferences API in NetBeans</h1>
- NetBeans adopts <a href="http://java.sun.com/j2se/1.5.0/docs/guide/preferences/">Java Preferences API</a>
+ NetBeans adopts <a href="https://docs.oracle.com/javase/1.5.0/docs/guide/preferences/">Java Preferences API</a>
standard to be used in NetBeans to
store preference and configuration data to be able to adapt to the needs
of different users. NetBeans keeps this standard and enhances it slightly
@@ -52,7 +52,7 @@
<li><code>NbPreferences.root()</code> returns root preference node. </li>
<li><code>NbPreferences.forModule(class cls)</code> returns
preference node which <a
- href="@JDK@/java/util/prefs/Preferences.html#absolutePath%28%29">absolute path</a>
+ href="@JDK@/java/util/prefs/Preferences.html#absolutePath--">absolute path</a>
depends whether class provided as a parameter was loaded as a
part of any module or not. If so, then absolute path corresponds to
slashified code name base of module. If not, then absolute path
@@ -169,7 +169,7 @@
registering the option into your layer.
<H4 ALIGN=LEFT>How to document usage of Preferences API?</H4>
Answer properly arch questions like any other <A
- HREF="http://openide.netbeans.org/tutorial/api-design.html">APIs</A>. There was added new arch question related to
+ HREF="https://netbeans.apache.org/wiki/API_Design">APIs</A>. There was added new arch question related to
preferences (resources-preferences). See example:
<PRE>
<answer id="resources-preferences">
@@ -244,9 +244,9 @@ public class DerbyOptionsTest extends BasicTestForImport {
If the tests didn't pass then probably there is more complicated object graph
serialized then you must subclass <CODE>PropertyProcessor</CODE> and put your
own code in.
-(See as an example: <A HREF="http://www.netbeans.org/source/browse/ide/launcher/upgrade/src/org/netbeans/upgrade/systemoptions/TaskTagsProcessor.java?view=markup">TaskTagsProcessor</A>
+(See as an example: <A HREF="https://github.com/apache/netbeans/tree/master/nb/o.n.upgrader/src/org/netbeans/upgrade/systemoptions/TaskTagsProcessor.java">TaskTagsProcessor</A>
and here is a <A
- HREF="http://www.netbeans.org/source/browse/ide/launcher/upgrade/test/unit/src/org/netbeans/upgrade/systemoptions/ExampleSettingsTest.java?view=markup">test</A>).
+ HREF="https://github.com/apache/netbeans/tree/master/nb/o.n.upgrader/test/unit/src/org/netbeans/upgrade/systemoptions">test</A>).
<H4 ALIGN=LEFT>How to write tests that needs Preferences API?</H4>
Not persistent implementation of <code>java.util.prefs.Preferences</code>
is installed in place of the platform-specific default implementation for
diff --git a/platform/openide.util/src/org/openide/util/io/NbObjectInputStream.java b/platform/openide.util/src/org/openide/util/io/NbObjectInputStream.java
index 8ba9061817..5f8bbf1a7b 100644
--- a/platform/openide.util/src/org/openide/util/io/NbObjectInputStream.java
+++ b/platform/openide.util/src/org/openide/util/io/NbObjectInputStream.java
@@ -88,7 +88,7 @@ public class NbObjectInputStream extends ObjectInputStream {
* This method deals with some of this incompatibilites and provides the
* module owners a way how to fix some of them.
* <P>
- * When a class is read, the <link>Utilities.translate</link> is consulted
+ * When a class is read, the {@link org.openide.util.BaseUtilities#translate(String)} is consulted
* to find out what whether the name of the class is listed there and
* what new value is assigned to it. This allows complete rename of the
* serialized class. For example:
@@ -101,13 +101,13 @@ public class NbObjectInputStream extends ObjectInputStream {
* <code>serialVersionUID</code>. This was causing us a lot of problems,
* because people were forgetting to specify the <code>serialVersionUID</code>
* field in their sources and then it was hard to recover from it. Right
- * now we have a solution: Just use <link>Utilities.translate</link> framework
+ * now we have a solution: Just use {@link org.openide.util.BaseUtilities#translate(String)} framework
* to assing your class <code>org.yourpackage.YourClass</code> the same
* name as it had e.g. <code>org.yourpackage.YourClass</code>. This will
* be interpreted by this method as a hit to suppress <code>serialVersionUID</code>
* and the <code>NbObjectInputStream</code> will ignore its value.
* <P>
- * Please see <link>Utilities.translate</link> to learn how your module
+ * Please see {@link org.openide.util.BaseUtilities#translate(String)} to learn how your module
* can provide list of classes that changed name or want to suppress <code>serialVersionUID</code>.
*
*/
diff --git a/platform/openide.util/src/org/openide/util/io/OperationException.java b/platform/openide.util/src/org/openide/util/io/OperationException.java
index 1f41f8c545..e6bba4e53c 100644
--- a/platform/openide.util/src/org/openide/util/io/OperationException.java
+++ b/platform/openide.util/src/org/openide/util/io/OperationException.java
@@ -35,6 +35,7 @@ public class OperationException extends IOException {
private Exception ex;
/** Default constructor.
+ * @param ex encapsuled exception
*/
public OperationException(Exception ex) {
this.ex = ex;
diff --git a/platform/openide.util/src/org/openide/util/io/ReaderInputStream.java b/platform/openide.util/src/org/openide/util/io/ReaderInputStream.java
index 121d35eda3..0c6973a3e0 100644
--- a/platform/openide.util/src/org/openide/util/io/ReaderInputStream.java
+++ b/platform/openide.util/src/org/openide/util/io/ReaderInputStream.java
@@ -37,6 +37,7 @@ public class ReaderInputStream extends InputStream {
/** Creates new input stream from the given reader.
* Uses the platform default encoding.
* @param reader Input reader
+ * @throws IOException on IO failure
*/
public ReaderInputStream(Reader reader) throws IOException {
this.reader = reader;
@@ -47,7 +48,8 @@ public class ReaderInputStream extends InputStream {
/** Creates new input stream from the given reader and encoding.
* @param reader Input reader
- * @param encoding
+ * @param encoding encoding
+ * @throws IOException on IO failure
*/
public ReaderInputStream(Reader reader, String encoding)
throws IOException {
diff --git a/platform/openide.util/src/org/openide/util/io/SafeException.java b/platform/openide.util/src/org/openide/util/io/SafeException.java
index 335e5f8fd0..406dce3b06 100644
--- a/platform/openide.util/src/org/openide/util/io/SafeException.java
+++ b/platform/openide.util/src/org/openide/util/io/SafeException.java
@@ -33,6 +33,7 @@ public class SafeException extends FoldingIOException {
private Exception ex;
/** Default constructor.
+ * @param ex encapsuled exception
*/
public SafeException(Exception ex) {
super(ex, null);
diff --git a/platform/openide.util/src/org/openide/xml/EntityCatalog.java b/platform/openide.util/src/org/openide/xml/EntityCatalog.java
index 4dbaadd772..2b59779edb 100644
--- a/platform/openide.util/src/org/openide/xml/EntityCatalog.java
+++ b/platform/openide.util/src/org/openide/xml/EntityCatalog.java
@@ -37,7 +37,7 @@ import org.xml.sax.SAXException;
* <p>You can register your own instances via lookup to add to the resolver pool,
* but for reasons of performance and predictability during startup it is best to provide
* the entity (e.g. some DTD you define) as the contents of a file in
- * the system filesystem, in the <samp>/xml/entities/</samp> folder, where the file path
+ * the system filesystem, in the <code>/xml/entities/</code> folder, where the file path
* beneath this folder is based on the public ID as follows:
* <ol>
* <li>US-ASCII alphanumeric characters and '_' are left as is.
@@ -46,10 +46,10 @@ import org.xml.sax.SAXException;
* <li>Final '//EN' is dropped.
* <li>Exactly two forward slashes in a row are converted to one.
* </ol>
- * Thus for example the public ID <samp>-//NetBeans//Entity Mapping Registration 1.0//EN</samp>
- * would be looked for in the file <samp>/xml/entities/NetBeans/Entity_Mapping_Registration_1_0</samp>.
+ * Thus for example the public ID <code>-//NetBeans//Entity Mapping Registration 1.0//EN</code>
+ * would be looked for in the file <code>/xml/entities/NetBeans/Entity_Mapping_Registration_1_0</code>.
* Naturally this only works if you are defining a fixed number of entities.
- * <p>It is recommended that the entity file in <samp>/xml/entities/</samp> also be given a file
+ * <p>It is recommended that the entity file in <code>/xml/entities/</code> also be given a file
* attribute named <code>hint.originalPublicID</code> with a string value giving the public ID.
* This permits {@code org.netbeans.modules.xml.catalog} to display the entry properly.
* @author Petr Kuzel
@@ -71,6 +71,7 @@ public abstract class EntityCatalog implements EntityResolver {
/** Get a master entity catalog which can delegate to any others that have
* been registered via lookup.
+ * @return master entity catalog
*/
public static EntityCatalog getDefault() {
return instance;
diff --git a/platform/openide.util/src/org/openide/xml/XMLUtil.java b/platform/openide.util/src/org/openide/xml/XMLUtil.java
index 6b847db7bd..c7d643245c 100644
--- a/platform/openide.util/src/org/openide/xml/XMLUtil.java
+++ b/platform/openide.util/src/org/openide/xml/XMLUtil.java
@@ -91,6 +91,7 @@ public final class XMLUtil extends Object {
// ~~~~~~~~~~~~~~~~~~~~~ SAX related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/** Create a simple parser.
+ * @throws SAXException if a parser can not be created
* @return <code>createXMLReader(false, false)</code>
*/
public static XMLReader createXMLReader() throws SAXException {
@@ -99,7 +100,8 @@ public final class XMLUtil extends Object {
/** Create a simple parser, possibly validating.
* @param validate if true, a validating parser is returned
- * @return <code>createXMLReader(validate, false)</code>
+ * @throws SAXException if a parser can not be created
+ * @return <code>createXMLReader(validate, false)</code>
*/
public static XMLReader createXMLReader(boolean validate)
throws SAXException {
@@ -149,7 +151,7 @@ public final class XMLUtil extends Object {
/**
* Creates an empty DOM document. E.g.:
- * <p><pre>
+ * <pre>
* Document doc = createDocument("book", null, null, null);
* </pre><p>
* creates new DOM of a well-formed document with root element named book.
@@ -372,7 +374,7 @@ public final class XMLUtil extends Object {
* some CDATA sections my not be written as CDATA section or may be merged with
* other CDATA section at the same level. Also if plain text nodes are mixed with
* CDATA sections at the same level all text is likely to end up in one big CDATA section.
- * <br/>
+ * <br>
* For nodes that only have one CDATA section this method should work fine.
* </p>
*
@@ -588,7 +590,7 @@ public final class XMLUtil extends Object {
/**
* Escape passed string as XML element content (<code><</code>,
- * <code>&</code> and <code>><code> in <code>]]></code> sequences).
+ * <code>&</code> and <code>></code> in <code>]]></code> sequences).
*
* @param val a string to be escaped
*
@@ -638,7 +640,7 @@ public final class XMLUtil extends Object {
* @param val data to be converted
* @param start offset
* @param len count
- *
+ * @return converted data
* @since 1.29
*/
public static String toHex(byte[] val, int start, int len) {
@@ -659,7 +661,7 @@ public final class XMLUtil extends Object {
* @param hex data to be converted
* @param start offset
* @param len count
- *
+ * @return converted data
* @throws IOException if input does not represent hex encoded value
*
* @since 1.29
@@ -925,8 +927,9 @@ public final class XMLUtil extends Object {
* This compares localName (nodeName if localName is null) to name,
* and checks the tags namespace with the provided namespace.
* A <code>null</code> namespace will match any namespace.
- *
- * <ul>This is differs from the DOM version by:
+ * <p>
+ * This is differs from the DOM version by:
+ * <ul>
* <li>not searching recursively</li>
* <li>returns a single result</li>
* </ul>
@@ -986,7 +989,7 @@ public final class XMLUtil extends Object {
*
* @param from element to translate
* @param namespace namespace to be translated to
- * @return
+ * @return translated element
*
* @since 8.4
*/
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@netbeans.apache.org
For additional commands, e-mail: commits-help@netbeans.apache.org
For further information about the NetBeans mailing lists, visit:
https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists