Changeset 9231 in josm for trunk/src/org/openstreetmap/josm/tools

Timestamp:

2016-01-01T02:35:34+01:00 (8 years ago)

Author:

Don-vip

Message:

javadoc update

Location:

trunk/src/org/openstreetmap/josm/tools

Files:

• CheckParameterUtil.java (modified) (1 diff)
• CopyList.java (modified) (3 diffs)
• Diff.java (modified) (14 diffs)
• GBC.java (modified) (5 diffs)
• Geometry.java (modified) (1 diff)
• Shortcut.java (modified) (7 diffs)
• Utils.java (modified) (3 diffs)

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

@@ -98 +98 @@
      * Ensures that the condition {@code condition} holds.
      * @param condition The condition to check
+     * @param message error message
      * @throws IllegalArgumentException if the condition does not hold
      */

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

@@ -16 +16 @@
  *
  * @author nenik
+ * @param <E> the type of elements in this list
  */
 public final class CopyList<E> extends AbstractList<E> implements RandomAccess, Cloneable {
@@ -24 +25 @@
     /**
      * Create a List over given array.
-     * @param array The initial List content. The array is never modified
-     * by the {@code CopyList}.
+     * @param array The initial List content. The array is never modified by the {@code CopyList}.
      */
     public CopyList(E[] array) {
@@ -31 +31 @@
     }
 
+    /**
+     * Create a List over given array and size.
+     * @param array The initial List content. The array is never modified by the {@code CopyList}.
+     * @param size number of items
+     */
     public CopyList(E[] array, int size) {
         this.array = array;

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

@@ -152 +152 @@
      * the worst this can do is cause suboptimal diff output.
      * It cannot cause incorrect diff output.
+     * @param xoff xoff
+     * @param xlim xlim
+     * @param yoff yoff
+     * @param ylim ylim
+     * @return midpoint of the shortest edit script
      */
     private int diag(int xoff, int xlim, int yoff, int ylim) {
@@ -164 +169 @@
         int fmin = fmid, fmax = fmid;   // Limits of top-down search.
         int bmin = bmid, bmax = bmid;   // Limits of bottom-up search.
-        /* True if southeast corner is on an odd
-                     diagonal with respect to the northwest. */
+        // True if southeast corner is on an odd diagonal with respect to the northwest.
         final boolean odd = (fmid - bmid & 1) != 0;
 
@@ -315 +319 @@
     }
 
-    /** Compare in detail contiguous subsequences of the two files
-     which are known, as a whole, to match each other.
-
-     The results are recorded in the vectors filevec[N].changed_flag, by
-     storing a 1 in the element for each line that is an insertion or deletion.
-
-     The subsequence of file 0 is [XOFF, XLIM) and likewise for file 1.
-
-     Note that XLIM, YLIM are exclusive bounds.
-     All line numbers are origin-0 and discarded lines are not counted.  */
-
+    /**
+     * Compare in detail contiguous subsequences of the two files
+     * which are known, as a whole, to match each other.
+     *
+     * The results are recorded in the vectors filevec[N].changed_flag, by
+     * storing a 1 in the element for each line that is an insertion or deletion.
+     *
+     * The subsequence of file 0 is [XOFF, XLIM) and likewise for file 1.
+     *
+     * Note that XLIM, YLIM are exclusive bounds.
+     * All line numbers are origin-0 and discarded lines are not counted.
+     * @param xoff xoff
+     * @param xlim xlim
+     * @param yoff yoff
+     * @param ylim ylim
+     */
     private void compareseq(int xoff, int xlim, int yoff, int ylim) {
         /* Slide down the bottom initial diagonal. */
@@ -379 +388 @@
     private boolean inhibit;
 
-    /** Adjust inserts/deletes of blank lines to join changes
-        as much as possible.
+    /**
+     * Adjust inserts/deletes of blank lines to join changes as much as possible.
      */
     private void shift_boundaries() {
@@ -389 +398 @@
     }
 
+    /**
+     * Script builder.
+     */
     public interface ScriptBuilder {
-        /** Scan the tables of which lines are inserted and deleted,
-            producing an edit script.
-            @param changed0 true for lines in first file which do not match 2nd
-            @param len0 number of lines in first file
-            @param changed1 true for lines in 2nd file which do not match 1st
-            @param len1 number of lines in 2nd file
-            @return a linked list of changes - or null
+        /**
+         * Scan the tables of which lines are inserted and deleted, producing an edit script.
+         * @param changed0 true for lines in first file which do not match 2nd
+         * @param len0 number of lines in first file
+         * @param changed1 true for lines in 2nd file which do not match 1st
+         * @param len1 number of lines in 2nd file
+         * @return a linked list of changes - or null
          */
         Change build_script(
@@ -472 +484 @@
     }
 
-    /** Standard ScriptBuilders. */
-    public static final ScriptBuilder
-    forwardScript = new ForwardScript(),
-    reverseScript = new ReverseScript();
-
-    /** Report the differences of two files. DEPTH is the current directory depth. */
+    /** Standard Forward ScriptBuilder. */
+    public static final ScriptBuilder forwardScript = new ForwardScript();
+    /** Standard Reverse ScriptBuilder. */
+    public static final ScriptBuilder reverseScript = new ReverseScript();
+
+    /**
+     * Report the differences of two files. DEPTH is the current directory depth.
+     * @param reverse if {@code true} use {@link #reverseScript} else use {@link #forwardScript}
+     * @return the differences of two files
+     */
     public final Change diff_2(final boolean reverse) {
         return diff(reverse ? reverseScript : forwardScript);
     }
 
-    /** Get the results of comparison as an edit script.  The script
-     is described by a list of changes.  The standard ScriptBuilder
-     implementations provide for forward and reverse edit scripts.
-     Alternate implementations could, for instance, list common elements
-     instead of differences.
-     @param bld an object to build the script from change flags
-     @return the head of a list of changes
+    /**
+     * Get the results of comparison as an edit script.  The script
+     * is described by a list of changes.  The standard ScriptBuilder
+     * implementations provide for forward and reverse edit scripts.
+     * Alternate implementations could, for instance, list common elements
+     * instead of differences.
+     * @param bld an object to build the script from change flags
+     * @return the head of a list of changes
      */
     public Change diff(final ScriptBuilder bld) {
 
-        /* Some lines are obviously insertions or deletions
-       because they don't match anything.  Detect them now,
-       and avoid even thinking about them in the main comparison algorithm.  */
-
+        // Some lines are obviously insertions or deletions because they don't match anything.
+        // Detect them now, and avoid even thinking about them in the main comparison algorithm.
         discard_confusing_lines();
 
-        /* Now do the main comparison algorithm, considering just the
-       undiscarded lines.  */
-
+        // Now do the main comparison algorithm, considering just the undiscarded lines.
         xvec = filevec[0].undiscarded;
         yvec = filevec[1].undiscarded;
 
-        int diags =
-            filevec[0].nondiscardedLines + filevec[1].nondiscardedLines + 3;
+        int diags = filevec[0].nondiscardedLines + filevec[1].nondiscardedLines + 3;
         fdiag = new int[diags];
         fdiagoff = filevec[1].nondiscardedLines + 1;
@@ -512 +524 @@
 
         compareseq(0, filevec[0].nondiscardedLines,
-                0, filevec[1].nondiscardedLines);
+                   0, filevec[1].nondiscardedLines);
         fdiag = null;
         bdiag = null;
 
-        /* Modify the results slightly to make them prettier
-       in cases where that can validly be done.  */
-
+        // Modify the results slightly to make them prettier in cases where that can validly be done.
         shift_boundaries();
 
-        /* Get the results of comparison in the form of a chain
-       of `struct change's -- an edit script.  */
+        // Get the results of comparison in the form of a chain of `struct change's -- an edit script.
         return bld.build_script(
                 filevec[0].changedFlag,
@@ -529 +538 @@
                 filevec[1].bufferedLines
         );
-
     }
 
@@ -555 +563 @@
         public final int line1;
 
-        /** Cons an additional entry onto the front of an edit script OLD.
-       LINE0 and LINE1 are the first affected lines in the two files (origin 0).
-       DELETED is the number of lines deleted here from file 0.
-       INSERTED is the number of lines inserted here in file 1.
-
-       If DELETED is 0 then LINE0 is the number of the line before
-       which the insertion was done; vice versa for INSERTED and LINE1.  */
+        /**
+         * Cons an additional entry onto the front of an edit script OLD.
+         * LINE0 and LINE1 are the first affected lines in the two files (origin 0).
+         * DELETED is the number of lines deleted here from file 0.
+         * INSERTED is the number of lines inserted here in file 1.
+         *
+         * If DELETED is 0 then LINE0 is the number of the line before
+         * which the insertion was done; vice versa for INSERTED and LINE1.
+         * @param line0 first affected lines in the two files (origin 0)
+         * @param line1 first affected lines in the two files (origin 0)
+         * @param deleted the number of lines deleted here from file 0
+         * @param inserted the number of lines inserted here in file 1
+         * @param old edit script
+         */
         public Change(int line0, int line1, int deleted, int inserted, Change old) {
             this.line0 = line0;
@@ -573 +588 @@
          * Returns the number of insertions and deletions of this change as well as
          * (recursively) the changes linked via {@link #link}.
+         * @return recursive number of insertions and deletions
          */
         public int getTotalNumberOfChanges() {
@@ -585 +601 @@
     }
 
-    /** Data on one input file being compared.
+    /**
+     * Data on one input file being compared.
      */
     class FileData {
@@ -591 +608 @@
         /** Allocate changed array for the results of comparison.  */
         void clear() {
-            /* Allocate a flag for each line of each file, saying whether that line
-               is an insertion or deletion.
-               Allocate an extra element, always zero, at each end of each vector.
-             */
+            // Allocate a flag for each line of each file, saying whether that line is an insertion or deletion.
+            // Allocate an extra element, always zero, at each end of each vector.
             changedFlag = new boolean[bufferedLines + 2];
         }
 
-        /** Return equiv_count[I] as the number of lines in this file
-         that fall in equivalence class I.
-         @return the array of equivalence class counts.
+        /**
+         * Return equiv_count[I] as the number of lines in this file that fall in equivalence class I.
+         * @return the array of equivalence class counts.
          */
         int[] equivCount() {
@@ -610 +625 @@
         }
 
-        /** Discard lines that have no matches in another file.
-
-       A line which is discarded will not be considered by the actual
-       comparison algorithm; it will be as if that line were not in the file.
-       The file's `realindexes' table maps virtual line numbers
-       (which don't count the discarded lines) into real line numbers;
-       this is how the actual comparison algorithm produces results
-       that are comprehensible when the discarded lines are counted.
-<p>
-       When we discard a line, we also mark it as a deletion or insertion
-       so that it will be printed in the output.
-      @param f the other file
+        /**
+         * Discard lines that have no matches in another file.
+         *
+         * A line which is discarded will not be considered by the actual comparison algorithm;
+         * it will be as if that line were not in the file.
+         * The file's `realindexes' table maps virtual line numbers
+         * (which don't count the discarded lines) into real line numbers;
+         * this is how the actual comparison algorithm produces results
+         * that are comprehensible when the discarded lines are counted.
+         * <p>
+         * When we discard a line, we also mark it as a deletion or insertion so that it will be printed in the output.
+         * @param f the other file
          */
         void discard_confusing_lines(FileData f) {
             clear();
-            /* Set up table of which lines are going to be discarded. */
+            // Set up table of which lines are going to be discarded.
             final byte[] discarded = discardable(f.equivCount());
 
-            /* Don't really discard the provisional lines except when they occur
-       in a run of discardables, with nonprovisionals at the beginning
-       and end.  */
+            // Don't really discard the provisional lines except when they occur in a run of discardables,
+            // with nonprovisionals at the beginning and end.
             filterDiscards(discarded);
 
-            /* Actually discard the lines. */
+            // Actually discard the lines.
             discard(discarded);
         }
@@ -674 +688 @@
         /**
          * Don't really discard the provisional lines except when they occur
-         * in a run of discardables, with nonprovisionals at the beginning
-         * and end.
+         * in a run of discardables, with nonprovisionals at the beginning and end.
+         * @param discards discards
          */
         private void filterDiscards(final byte[] discards) {

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

@@ -124 +124 @@
     /**
      * Sets the constraint's {@code gridx}, {@code gridy}.
+     * @param gridx cell containing the leading edge of the component's display area
+     * @param gridy cell at the top of the component's display area
      * @return This constraint for chaining.
      * @see #gridx
@@ -136 +138 @@
     /**
      * Sets the constraint's {@code gridwidth}, {@code gridheight}.
+     * @param gridwidth number of cells in a row for the component's display area
+     * @param gridheight number of cells in a column for the component's display area
      * @return This constraint for chaining.
      * @see #gridwidth
@@ -148 +152 @@
     /**
      * Sets the constraint's {@code gridwidth}.
+     * @param gridwidth number of cells in a row for the component's display area
      * @return This constraint for chaining.
      * @see #gridwidth
@@ -160 +165 @@
      *
      * Is equivalent to {@code std().grid(gridx, gridy)}
+     * @param gridx cell containing the leading edge of the component's display area
+     * @param gridy cell at the top of the component's display area
      * @return A standard constraint.
      * @see #std()
@@ -169 +176 @@
         return std().grid(gridx, gridy);
     }
-
 }

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

@@ -258 +258 @@
 
     /**
-     * Finds the intersection of two line segments
+     * Finds the intersection of two line segments.
+     * @param p1 the coordinates of the start point of the first specified line segment
+     * @param p2 the coordinates of the end point of the first specified line segment
+     * @param p3 the coordinates of the start point of the second specified line segment
+     * @param p4 the coordinates of the end point of the second specified line segment
      * @return EastNorth null if no intersection was found, the EastNorth coordinates of the intersection otherwise
      */

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

@@ -123 +123 @@
 
     /**
-     * FOR PREF PANE ONLY
+     * FOR PREF PANE ONLY.<p>
+     * Sets the modifiers that are used.
+     * @param assignedModifier assigned modifier
      */
     public void setAssignedModifier(int assignedModifier) {
@@ -130 +132 @@
 
     /**
-     * FOR PREF PANE ONLY
+     * FOR PREF PANE ONLY.<p>
+     * Sets the key that actually is used.
+     * @param assignedKey assigned key
      */
     public void setAssignedKey(int assignedKey) {
@@ -137 +141 @@
 
     /**
-     * FOR PREF PANE ONLY
+     * FOR PREF PANE ONLY.<p>
+     * Sets whether the user has changed this shortcut.
+     * @param assignedUser {@code true} if the user has changed this shortcut
      */
     public void setAssignedUser(boolean assignedUser) {
@@ -202 +208 @@
     /**
      * use this to set a menu's mnemonic
+     * @param menu menu
      */
     public void setMnemonic(JMenu menu) {
@@ -211 +218 @@
     /**
      * use this to set a buttons's mnemonic
+     * @param button button
      */
     public void setMnemonic(AbstractButton button) {
@@ -220 +228 @@
     /**
      * Sets the mnemonic key on a text component.
+     * @param component component
      */
     public void setFocusAccelerator(JTextComponent component) {
@@ -229 +238 @@
     /**
      * use this to set a actions's accelerator
+     * @param action action
      */
     public void setAccelerator(AbstractAction action) {

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

@@ -77 +77 @@
 public final class Utils {
 
+    /** Pattern matching white spaces */
     public static final Pattern WHITE_SPACES_PATTERN = Pattern.compile("\\s+");
 
@@ -311 +312 @@
      * convert float range 0 <= x <= 1 to integer range 0..255
      * when dealing with colors and color alpha value
+     * @param val float value between 0 and 1
      * @return null if val is null, the corresponding int if val is in the
      *         range 0...1. If val is outside that range, return 255
@@ -336 +338 @@
     }
 
+    /**
+     * Returns the complementary color of {@code clr}.
+     * @param clr the color to complement
+     * @return the complementary color of {@code clr}
+     */
     public static Color complement(Color clr) {
         return new Color(255 - clr.getRed(), 255 - clr.getGreen(), 255 - clr.getBlue(), clr.getAlpha());