Changeset 8928 in josm for trunk

Timestamp:

2015-10-22T14:35:57+02:00 (8 years ago)

Author:

Don-vip

Message:

javadoc fixes

Location:

trunk/src/org/openstreetmap/josm

Files:

• plugins/Plugin.java (modified) (2 diffs)
• plugins/PluginHandler.java (modified) (1 diff)
• tools/AlphanumComparator.java (modified) (1 diff)
• tools/AudioPlayer.java (modified) (10 diffs)
• tools/Diff.java (modified) (2 diffs)
• tools/Geometry.java (modified) (2 diffs)
• tools/Predicates.java (modified) (9 diffs)
• tools/Shortcut.java (modified) (5 diffs)
• tools/TextTagParser.java (modified) (2 diffs)
• tools/Utils.java (modified) (5 diffs)

trunk/src/org/openstreetmap/josm/plugins/Plugin.java

@@ -92 +92 @@
      * Called in the preferences dialog to create a preferences page for the plugin,
      * if any available.
+     * @return the preferences dialog, or {@code null}
      */
     public PreferenceSetting getPreferenceSetting() {
@@ -141 +142 @@
      *
      * (Note the missing leading "/".)
+     * @return a class loader for loading resources from the plugin jar
      */
     public ClassLoader getPluginResourceClassLoader() {

trunk/src/org/openstreetmap/josm/plugins/PluginHandler.java

@@ -953 +953 @@
      * @param monitor the progress monitor. Defaults to {@link NullProgressMonitor#INSTANCE} if null.
      * @param displayErrMsg if {@code true}, a blocking error message is displayed in case of I/O exception.
+     * @return the list of plugins to load
      * @throws IllegalArgumentException if plugins is null
      */

trunk/src/org/openstreetmap/josm/tools/AlphanumComparator.java

@@ -61 +61 @@
 
     /**
-     * Length of string is passed in for improved efficiency (only need to
-     * calculate it once) *
+     * Returns an alphanum chunk.
+     * Length of string is passed in for improved efficiency (only need to calculate it once).
+     * @param s string
+     * @param slength string length
+     * @param marker position
+     * @return alphanum chunk found at given position
      */
     private static String getChunk(String s, int slength, int marker) {

trunk/src/org/openstreetmap/josm/tools/AudioPlayer.java

@@ -123 +123 @@
      */
     public static void play(URL url) throws Exception {
-        AudioPlayer.get().command.play(url, 0.0, 1.0);
+        AudioPlayer.getInstance().command.play(url, 0.0, 1.0);
     }
 
@@ -133 +133 @@
      */
     public static void play(URL url, double seconds) throws Exception {
-        AudioPlayer.get().command.play(url, seconds, 1.0);
+        AudioPlayer.getInstance().command.play(url, seconds, 1.0);
     }
 
@@ -144 +144 @@
      */
     public static void play(URL url, double seconds, double speed) throws Exception {
-        AudioPlayer.get().command.play(url, seconds, speed);
+        AudioPlayer.getInstance().command.play(url, seconds, speed);
     }
 
@@ -152 +152 @@
      */
     public static void pause() throws Exception {
-        AudioPlayer.get().command.pause();
+        AudioPlayer.getInstance().command.pause();
     }
 
@@ -160 +160 @@
      */
     public static URL url() {
-        return AudioPlayer.get().playingUrl;
+        return AudioPlayer.getInstance().playingUrl;
     }
 
@@ -168 +168 @@
      */
     public static boolean paused() {
-        return AudioPlayer.get().state == State.PAUSED;
+        return AudioPlayer.getInstance().state == State.PAUSED;
     }
 
@@ -176 +176 @@
      */
     public static boolean playing() {
-        return AudioPlayer.get().state == State.PLAYING;
+        return AudioPlayer.getInstance().state == State.PLAYING;
     }
 
@@ -184 +184 @@
      */
     public static double position() {
-        return AudioPlayer.get().position;
+        return AudioPlayer.getInstance().position;
     }
 
@@ -192 +192 @@
      */
     public static double speed() {
-        return AudioPlayer.get().speed;
-    }
-
-    /**
-     *  gets the singleton object, and if this is the first time, creates it along with
-     *  the thread to support audio
-     */
-    private static AudioPlayer get() {
+        return AudioPlayer.getInstance().speed;
+    }
+
+    /**
+     * Returns the singleton object, and if this is the first time, creates it along with
+     * the thread to support audio
+     * @return the unique instance
+     */
+    private static AudioPlayer getInstance() {
         if (audioPlayer != null)
             return audioPlayer;
@@ -206 +207 @@
             return audioPlayer;
         } catch (Exception ex) {
+            Main.error(ex);
             return null;
         }

trunk/src/org/openstreetmap/josm/tools/Diff.java

@@ -128 +128 @@
     private static final int SNAKE_LIMIT = 20;
 
-    /** Find the midpoint of the shortest edit script for a specified
-     portion of the two files.
-
-     We scan from the beginnings of the files, and simultaneously from the ends,
-     doing a breadth-first search through the space of edit-sequence.
-     When the two searches meet, we have found the midpoint of the shortest
-     edit sequence.
-
-     The value returned is the number of the diagonal on which the midpoint lies.
-     The diagonal number equals the number of inserted lines minus the number
-     of deleted lines (counting only lines before the midpoint).
-     The edit cost is stored into COST; this is the total number of
-     lines inserted or deleted (counting only lines before the midpoint).
-
-     This function assumes that the first lines of the specified portions
-     of the two files do not match, and likewise that the last lines do not
-     match.  The caller must trim matching lines from the beginning and end
-     of the portions it is going to specify.
-
-     Note that if we return the "wrong" diagonal value, or if
-     the value of bdiag at that diagonal is "wrong",
-     the worst this can do is cause suboptimal diff output.
-     It cannot cause incorrect diff output.  */
-
+    /**
+     * Find the midpoint of the shortest edit script for a specified
+     * portion of the two files.
+     *
+     * We scan from the beginnings of the files, and simultaneously from the ends,
+     * doing a breadth-first search through the space of edit-sequence.
+     * When the two searches meet, we have found the midpoint of the shortest
+     * edit sequence.
+     *
+     * The value returned is the number of the diagonal on which the midpoint lies.
+     * The diagonal number equals the number of inserted lines minus the number
+     * of deleted lines (counting only lines before the midpoint).
+     * The edit cost is stored into COST; this is the total number of
+     * lines inserted or deleted (counting only lines before the midpoint).
+     *
+     * This function assumes that the first lines of the specified portions
+     * of the two files do not match, and likewise that the last lines do not
+     * match.  The caller must trim matching lines from the beginning and end
+     * of the portions it is going to specify.
+     *
+     * Note that if we return the "wrong" diagonal value, or if
+     * the value of bdiag at that diagonal is "wrong",
+     * the worst this can do is cause suboptimal diff output.
+     * It cannot cause incorrect diff output.
+     */
     private int diag(int xoff, int xlim, int yoff, int ylim) {
         final int[] fd = fdiag; // Give the compiler a chance.
@@ -476 +477 @@
     reverseScript = new ReverseScript();
 
-    /** Report the differences of two files.  DEPTH is the current directory
-        depth. */
+    /** Report the differences of two files. DEPTH is the current directory depth. */
     public final Change diff_2(final boolean reverse) {
         return diff(reverse ? reverseScript : forwardScript);

trunk/src/org/openstreetmap/josm/tools/Geometry.java

@@ -876 +876 @@
      * Tests if the {@code node} is inside the multipolygon {@code multiPolygon}. The nullable argument
      * {@code isOuterWayAMatch} allows to decide if the immediate {@code outer} way of the multipolygon is a match.
+     * @param node node
+     * @param multiPolygon multipolygon
+     * @param isOuterWayAMatch allows to decide if the immediate {@code outer} way of the multipolygon is a match
+     * @return {@code true} if the node is inside the multipolygon
      */
     public static boolean isNodeInsideMultiPolygon(Node node, Relation multiPolygon, Predicate<Way> isOuterWayAMatch) {
@@ -886 +890 @@
      * <p>
      * If {@code nodes} contains exactly one element, then it is checked whether that one node is inside the multipolygon.
+     * @param nodes nodes forming the polygon
+     * @param multiPolygon multipolygon
+     * @param isOuterWayAMatch allows to decide if the immediate {@code outer} way of the multipolygon is a match
+     * @return {@code true} if the polygon formed by nodes is inside the multipolygon
      */
     public static boolean isPolygonInsideMultiPolygon(List<Node> nodes, Relation multiPolygon, Predicate<Way> isOuterWayAMatch) {

trunk/src/org/openstreetmap/josm/tools/Predicates.java

@@ -18 +18 @@
     /**
      * Returns the negation of {@code predicate}.
+     * @param predicate the predicate to negate
+     * @return the negation of {@code predicate}
      */
     public static <T> Predicate<T> not(final Predicate<T> predicate) {
@@ -30 +32 @@
     /**
      * Returns a {@link Predicate} executing {@link Objects#equals}.
+     * @param ref the reference object
+     * @return a {@link Predicate} executing {@link Objects#equals}
      */
     public static <T> Predicate<T> equalTo(final T ref) {
@@ -42 +46 @@
     /**
      * Returns a {@link Predicate} executing {@link Pattern#matcher(CharSequence)} and {@link java.util.regex.Matcher#matches}.
+     * @param pattern the pattern
+     * @return a {@link Predicate} executing {@link Pattern#matcher(CharSequence)} and {@link java.util.regex.Matcher#matches}
      */
     public static Predicate<String> stringMatchesPattern(final Pattern pattern) {
@@ -54 +60 @@
     /**
      * Returns a {@link Predicate} executing {@link Pattern#matcher(CharSequence)} and {@link java.util.regex.Matcher#find}.
+     * @param pattern the pattern
+     * @return a {@link Predicate} executing {@link Pattern#matcher(CharSequence)} and {@link java.util.regex.Matcher#find}
      */
     public static Predicate<String> stringContainsPattern(final Pattern pattern) {
@@ -66 +74 @@
     /**
      * Returns a {@link Predicate} executing {@link String#contains(CharSequence)}.
+     * @param pattern the pattern
+     * @return a {@link Predicate} executing {@link String#contains(CharSequence)}
      */
     public static Predicate<String> stringContains(final String pattern) {
@@ -78 +88 @@
     /**
      * Returns a {@link Predicate} executing {@link OsmPrimitive#hasTag(String, String...)}.
+     * @param key the key forming the tag
+     * @param values one or many values forming the tag
+     * @return a {@link Predicate} executing {@link OsmPrimitive#hasTag(String, String...)}
      */
     public static Predicate<OsmPrimitive> hasTag(final String key, final String... values) {
@@ -90 +103 @@
     /**
      * Returns a {@link Predicate} executing {@link OsmPrimitive#hasKey(String)}.
+     * @param key the key
+     * @return a {@link Predicate} executing {@link OsmPrimitive#hasKey(String)}
      */
     public static Predicate<OsmPrimitive> hasKey(final String key) {
@@ -102 +117 @@
     /**
      * Returns a {@link Predicate} executing {@link Collection#contains(Object)}.
+     * @param target collection
+     * @return a {@link Predicate} executing {@link Collection#contains(Object)}
      */
     public static <T> Predicate<T> inCollection(final Collection<? extends T> target) {
@@ -114 +131 @@
     /**
      * Returns a {@link Predicate} testing whether objects are {@code null}.
+     * @return a {@link Predicate} testing whether objects are {@code null}
      */
     public static <T> Predicate<T> isNull() {

trunk/src/org/openstreetmap/josm/tools/Shortcut.java

@@ -152 +152 @@
     /**
      * Use this to register the shortcut with Swing
+     * @return the key stroke
      */
     public KeyStroke getKeyStroke() {
@@ -233 +234 @@
 
     /**
-     * use this to get a human readable text for your shortcut
+     * Returns a human readable text for the shortcut.
+     * @return a human readable text for the shortcut
      */
     public String getKeyText() {
@@ -270 +272 @@
 
     /**
-     * FOR PREF PANE ONLY
+     * Returns a list of all shortcuts.
+     * @return a list of all shortcuts
      */
     public static List<Shortcut> listAll() {
@@ -384 +387 @@
 
     /**
-     * FOR PLATFORMHOOK USE ONLY
-     *
+     * FOR PLATFORMHOOK USE ONLY.
+     * <p>
      * This registers a system shortcut. See PlatformHook for details.
+     * @param shortText an ID. re-use a {@code "system:*"} ID if possible, else use something unique.
+     * @param longText this will be displayed in the shortcut preferences dialog. Better
+     * use something the user will recognize...
+     * @param key the key. Use a {@link KeyEvent KeyEvent.VK_*} constant here.
+     * @param modifier the modifier. Use a {@link KeyEvent KeyEvent.*_MASK} constant here.
+     * @return the system shortcut
      */
     public static Shortcut registerSystemShortcut(String shortText, String longText, int key, int modifier) {
@@ -416 +425 @@
      * @param requestedGroup the group this shortcut fits best. This will determine the
      * modifiers your shortcut will get assigned. Use the constants defined above.
+     * @return the shortcut
      */
     public static Shortcut registerShortcut(String shortText, String longText, int requestedKey, int requestedGroup) {

trunk/src/org/openstreetmap/josm/tools/TextTagParser.java

@@ -55 +55 @@
         /**
          * Read tags from "Free format"
+         * @return map of tags
          */
-        Map<String, String>  getFreeParsedTags() {
+        private Map<String, String> getFreeParsedTags() {
             String k, v;
             Map<String, String> tags = new HashMap<>();
@@ -168 +169 @@
      * @param tagRegex - each part is matched against this regex
      * @param unescapeTextInQuotes - if true, matched tag and value will be analyzed more thoroughly
+     * @return map of tags
      */
     public static Map<String, String> readTagsByRegexp(String text, String splitRegex, String tagRegex, boolean unescapeTextInQuotes) {

trunk/src/org/openstreetmap/josm/tools/Utils.java

@@ -88 +88 @@
 
     /**
-     * Tests whether {@code predicate} applies to at least one elements from {@code collection}.
+     * Tests whether {@code predicate} applies to at least one element from {@code collection}.
+     * @param collection the collection
+     * @param predicate the predicate
+     * @return {@code true} if {@code predicate} applies to at least one element from {@code collection}
      */
     public static <T> boolean exists(Iterable<? extends T> collection, Predicate<? super T> predicate) {
@@ -100 +103 @@
     /**
      * Tests whether {@code predicate} applies to all elements from {@code collection}.
+     * @param collection the collection
+     * @param predicate the predicate
+     * @return {@code true} if {@code predicate} applies to all elements from {@code collection}
      */
     public static <T> boolean forAll(Iterable<? extends T> collection, Predicate<? super T> predicate) {
@@ -152 +158 @@
      * Filter a collection by (sub)class.
      * This is an efficient read-only implementation.
+     * @param collection the collection
+     * @param klass the (sub)class
+     * @return a read-only filtered collection
      */
     public static <S, T extends S> SubclassFilteredCollection<S, T> filteredCollection(Collection<S> collection, final Class<T> klass) {
@@ -281 +290 @@
      * convert Color to String
      * (Color.toString() omits alpha value)
+     * @param c the color
+     * @return the String representation, including alpha
      */
     public static String toString(Color c) {
@@ -308 +319 @@
      * convert integer range 0..255 to float range 0 &lt;= x &lt;= 1
      * when dealing with colors and color alpha value
+     * @param val integer value
+     * @return corresponding float value in range 0 &lt;= x &lt;= 1
      */
     public static Float color_int2float(Integer val) {