Index: /trunk/src/org/openstreetmap/josm/plugins/Plugin.java =================================================================== --- /trunk/src/org/openstreetmap/josm/plugins/Plugin.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/plugins/Plugin.java (revision 8928) @@ -92,4 +92,5 @@ * 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,4 +142,5 @@ * * (Note the missing leading "/".) + * @return a class loader for loading resources from the plugin jar */ public ClassLoader getPluginResourceClassLoader() { Index: /trunk/src/org/openstreetmap/josm/plugins/PluginHandler.java =================================================================== --- /trunk/src/org/openstreetmap/josm/plugins/PluginHandler.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/plugins/PluginHandler.java (revision 8928) @@ -953,4 +953,5 @@ * @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 */ Index: /trunk/src/org/openstreetmap/josm/tools/AlphanumComparator.java =================================================================== --- /trunk/src/org/openstreetmap/josm/tools/AlphanumComparator.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/tools/AlphanumComparator.java (revision 8928) @@ -61,6 +61,10 @@ /** - * 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) { Index: /trunk/src/org/openstreetmap/josm/tools/AudioPlayer.java =================================================================== --- /trunk/src/org/openstreetmap/josm/tools/AudioPlayer.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/tools/AudioPlayer.java (revision 8928) @@ -123,5 +123,5 @@ */ 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,5 +133,5 @@ */ 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,5 +144,5 @@ */ 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,5 +152,5 @@ */ public static void pause() throws Exception { - AudioPlayer.get().command.pause(); + AudioPlayer.getInstance().command.pause(); } @@ -160,5 +160,5 @@ */ public static URL url() { - return AudioPlayer.get().playingUrl; + return AudioPlayer.getInstance().playingUrl; } @@ -168,5 +168,5 @@ */ public static boolean paused() { - return AudioPlayer.get().state == State.PAUSED; + return AudioPlayer.getInstance().state == State.PAUSED; } @@ -176,5 +176,5 @@ */ public static boolean playing() { - return AudioPlayer.get().state == State.PLAYING; + return AudioPlayer.getInstance().state == State.PLAYING; } @@ -184,5 +184,5 @@ */ public static double position() { - return AudioPlayer.get().position; + return AudioPlayer.getInstance().position; } @@ -192,12 +192,13 @@ */ 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,4 +207,5 @@ return audioPlayer; } catch (Exception ex) { + Main.error(ex); return null; } Index: /trunk/src/org/openstreetmap/josm/tools/Diff.java =================================================================== --- /trunk/src/org/openstreetmap/josm/tools/Diff.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/tools/Diff.java (revision 8928) @@ -128,28 +128,29 @@ 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,6 +477,5 @@ 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); Index: /trunk/src/org/openstreetmap/josm/tools/Geometry.java =================================================================== --- /trunk/src/org/openstreetmap/josm/tools/Geometry.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/tools/Geometry.java (revision 8928) @@ -876,4 +876,8 @@ * 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 isOuterWayAMatch) { @@ -886,4 +890,8 @@ *

* 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 nodes, Relation multiPolygon, Predicate isOuterWayAMatch) { Index: /trunk/src/org/openstreetmap/josm/tools/Predicates.java =================================================================== --- /trunk/src/org/openstreetmap/josm/tools/Predicates.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/tools/Predicates.java (revision 8928) @@ -18,4 +18,6 @@ /** * Returns the negation of {@code predicate}. + * @param predicate the predicate to negate + * @return the negation of {@code predicate} */ public static Predicate not(final Predicate predicate) { @@ -30,4 +32,6 @@ /** * Returns a {@link Predicate} executing {@link Objects#equals}. + * @param ref the reference object + * @return a {@link Predicate} executing {@link Objects#equals} */ public static Predicate equalTo(final T ref) { @@ -42,4 +46,6 @@ /** * 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 stringMatchesPattern(final Pattern pattern) { @@ -54,4 +60,6 @@ /** * 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 stringContainsPattern(final Pattern pattern) { @@ -66,4 +74,6 @@ /** * 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 stringContains(final String pattern) { @@ -78,4 +88,7 @@ /** * 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 hasTag(final String key, final String... values) { @@ -90,4 +103,6 @@ /** * 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 hasKey(final String key) { @@ -102,4 +117,6 @@ /** * Returns a {@link Predicate} executing {@link Collection#contains(Object)}. + * @param target collection + * @return a {@link Predicate} executing {@link Collection#contains(Object)} */ public static Predicate inCollection(final Collection target) { @@ -114,4 +131,5 @@ /** * Returns a {@link Predicate} testing whether objects are {@code null}. + * @return a {@link Predicate} testing whether objects are {@code null} */ public static Predicate isNull() { Index: /trunk/src/org/openstreetmap/josm/tools/Shortcut.java =================================================================== --- /trunk/src/org/openstreetmap/josm/tools/Shortcut.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/tools/Shortcut.java (revision 8928) @@ -152,4 +152,5 @@ /** * Use this to register the shortcut with Swing + * @return the key stroke */ public KeyStroke getKeyStroke() { @@ -233,5 +234,6 @@ /** - * 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,5 +272,6 @@ /** - * FOR PREF PANE ONLY + * Returns a list of all shortcuts. + * @return a list of all shortcuts */ public static List listAll() { @@ -384,7 +387,13 @@ /** - * FOR PLATFORMHOOK USE ONLY - * + * FOR PLATFORMHOOK USE ONLY. + *

* 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,4 +425,5 @@ * @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) { Index: /trunk/src/org/openstreetmap/josm/tools/TextTagParser.java =================================================================== --- /trunk/src/org/openstreetmap/josm/tools/TextTagParser.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/tools/TextTagParser.java (revision 8928) @@ -55,6 +55,7 @@ /** * Read tags from "Free format" + * @return map of tags */ - Map getFreeParsedTags() { + private Map getFreeParsedTags() { String k, v; Map tags = new HashMap<>(); @@ -168,4 +169,5 @@ * @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 readTagsByRegexp(String text, String splitRegex, String tagRegex, boolean unescapeTextInQuotes) { Index: /trunk/src/org/openstreetmap/josm/tools/Utils.java =================================================================== --- /trunk/src/org/openstreetmap/josm/tools/Utils.java (revision 8927) +++ /trunk/src/org/openstreetmap/josm/tools/Utils.java (revision 8928) @@ -88,5 +88,8 @@ /** - * 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 boolean exists(Iterable collection, Predicate predicate) { @@ -100,4 +103,7 @@ /** * 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 boolean forAll(Iterable collection, Predicate predicate) { @@ -152,4 +158,7 @@ * 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 SubclassFilteredCollection filteredCollection(Collection collection, final Class klass) { @@ -281,4 +290,6 @@ * 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,4 +319,6 @@ * convert integer range 0..255 to float range 0 <= x <= 1 * when dealing with colors and color alpha value + * @param val integer value + * @return corresponding float value in range 0 <= x <= 1 */ public static Float color_int2float(Integer val) {