Ignore:
Timestamp:
2016-01-01T02:35:34+01:00 (4 years ago)
Author:
Don-vip
Message:

javadoc update

Location:
trunk/src/org/openstreetmap/josm/tools
Files:
7 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/org/openstreetmap/josm/tools/CheckParameterUtil.java

    r8506 r9231  
    9898     * Ensures that the condition {@code condition} holds.
    9999     * @param condition The condition to check
     100     * @param message error message
    100101     * @throws IllegalArgumentException if the condition does not hold
    101102     */
  • trunk/src/org/openstreetmap/josm/tools/CopyList.java

    r8840 r9231  
    1616 *
    1717 * @author nenik
     18 * @param <E> the type of elements in this list
    1819 */
    1920public final class CopyList<E> extends AbstractList<E> implements RandomAccess, Cloneable {
     
    2425    /**
    2526     * Create a List over given array.
    26      * @param array The initial List content. The array is never modified
    27      * by the {@code CopyList}.
     27     * @param array The initial List content. The array is never modified by the {@code CopyList}.
    2828     */
    2929    public CopyList(E[] array) {
     
    3131    }
    3232
     33    /**
     34     * Create a List over given array and size.
     35     * @param array The initial List content. The array is never modified by the {@code CopyList}.
     36     * @param size number of items
     37     */
    3338    public CopyList(E[] array, int size) {
    3439        this.array = array;
  • trunk/src/org/openstreetmap/josm/tools/Diff.java

    r8976 r9231  
    152152     * the worst this can do is cause suboptimal diff output.
    153153     * It cannot cause incorrect diff output.
     154     * @param xoff xoff
     155     * @param xlim xlim
     156     * @param yoff yoff
     157     * @param ylim ylim
     158     * @return midpoint of the shortest edit script
    154159     */
    155160    private int diag(int xoff, int xlim, int yoff, int ylim) {
     
    164169        int fmin = fmid, fmax = fmid;   // Limits of top-down search.
    165170        int bmin = bmid, bmax = bmid;   // Limits of bottom-up search.
    166         /* True if southeast corner is on an odd
    167                      diagonal with respect to the northwest. */
     171        // True if southeast corner is on an odd diagonal with respect to the northwest.
    168172        final boolean odd = (fmid - bmid & 1) != 0;
    169173
     
    315319    }
    316320
    317     /** Compare in detail contiguous subsequences of the two files
    318      which are known, as a whole, to match each other.
    319 
    320      The results are recorded in the vectors filevec[N].changed_flag, by
    321      storing a 1 in the element for each line that is an insertion or deletion.
    322 
    323      The subsequence of file 0 is [XOFF, XLIM) and likewise for file 1.
    324 
    325      Note that XLIM, YLIM are exclusive bounds.
    326      All line numbers are origin-0 and discarded lines are not counted.  */
    327 
     321    /**
     322     * Compare in detail contiguous subsequences of the two files
     323     * which are known, as a whole, to match each other.
     324     *
     325     * The results are recorded in the vectors filevec[N].changed_flag, by
     326     * storing a 1 in the element for each line that is an insertion or deletion.
     327     *
     328     * The subsequence of file 0 is [XOFF, XLIM) and likewise for file 1.
     329     *
     330     * Note that XLIM, YLIM are exclusive bounds.
     331     * All line numbers are origin-0 and discarded lines are not counted.
     332     * @param xoff xoff
     333     * @param xlim xlim
     334     * @param yoff yoff
     335     * @param ylim ylim
     336     */
    328337    private void compareseq(int xoff, int xlim, int yoff, int ylim) {
    329338        /* Slide down the bottom initial diagonal. */
     
    379388    private boolean inhibit;
    380389
    381     /** Adjust inserts/deletes of blank lines to join changes
    382        as much as possible.
     390    /**
     391     * Adjust inserts/deletes of blank lines to join changes as much as possible.
    383392     */
    384393    private void shift_boundaries() {
     
    389398    }
    390399
     400    /**
     401     * Script builder.
     402     */
    391403    public interface ScriptBuilder {
    392         /** Scan the tables of which lines are inserted and deleted,
    393            producing an edit script.
    394            @param changed0 true for lines in first file which do not match 2nd
    395            @param len0 number of lines in first file
    396            @param changed1 true for lines in 2nd file which do not match 1st
    397            @param len1 number of lines in 2nd file
    398            @return a linked list of changes - or null
     404        /**
     405         * Scan the tables of which lines are inserted and deleted, producing an edit script.
     406         * @param changed0 true for lines in first file which do not match 2nd
     407         * @param len0 number of lines in first file
     408         * @param changed1 true for lines in 2nd file which do not match 1st
     409         * @param len1 number of lines in 2nd file
     410         * @return a linked list of changes - or null
    399411         */
    400412        Change build_script(
     
    472484    }
    473485
    474     /** Standard ScriptBuilders. */
    475     public static final ScriptBuilder
    476     forwardScript = new ForwardScript(),
    477     reverseScript = new ReverseScript();
    478 
    479     /** Report the differences of two files. DEPTH is the current directory depth. */
     486    /** Standard Forward ScriptBuilder. */
     487    public static final ScriptBuilder forwardScript = new ForwardScript();
     488    /** Standard Reverse ScriptBuilder. */
     489    public static final ScriptBuilder reverseScript = new ReverseScript();
     490
     491    /**
     492     * Report the differences of two files. DEPTH is the current directory depth.
     493     * @param reverse if {@code true} use {@link #reverseScript} else use {@link #forwardScript}
     494     * @return the differences of two files
     495     */
    480496    public final Change diff_2(final boolean reverse) {
    481497        return diff(reverse ? reverseScript : forwardScript);
    482498    }
    483499
    484     /** Get the results of comparison as an edit script.  The script
    485      is described by a list of changes.  The standard ScriptBuilder
    486      implementations provide for forward and reverse edit scripts.
    487      Alternate implementations could, for instance, list common elements
    488      instead of differences.
    489      @param bld an object to build the script from change flags
    490      @return the head of a list of changes
     500    /**
     501     * Get the results of comparison as an edit script.  The script
     502     * is described by a list of changes.  The standard ScriptBuilder
     503     * implementations provide for forward and reverse edit scripts.
     504     * Alternate implementations could, for instance, list common elements
     505     * instead of differences.
     506     * @param bld an object to build the script from change flags
     507     * @return the head of a list of changes
    491508     */
    492509    public Change diff(final ScriptBuilder bld) {
    493510
    494         /* Some lines are obviously insertions or deletions
    495        because they don't match anything.  Detect them now,
    496        and avoid even thinking about them in the main comparison algorithm.  */
    497 
     511        // Some lines are obviously insertions or deletions because they don't match anything.
     512        // Detect them now, and avoid even thinking about them in the main comparison algorithm.
    498513        discard_confusing_lines();
    499514
    500         /* Now do the main comparison algorithm, considering just the
    501        undiscarded lines.  */
    502 
     515        // Now do the main comparison algorithm, considering just the undiscarded lines.
    503516        xvec = filevec[0].undiscarded;
    504517        yvec = filevec[1].undiscarded;
    505518
    506         int diags =
    507             filevec[0].nondiscardedLines + filevec[1].nondiscardedLines + 3;
     519        int diags = filevec[0].nondiscardedLines + filevec[1].nondiscardedLines + 3;
    508520        fdiag = new int[diags];
    509521        fdiagoff = filevec[1].nondiscardedLines + 1;
     
    512524
    513525        compareseq(0, filevec[0].nondiscardedLines,
    514                 0, filevec[1].nondiscardedLines);
     526                   0, filevec[1].nondiscardedLines);
    515527        fdiag = null;
    516528        bdiag = null;
    517529
    518         /* Modify the results slightly to make them prettier
    519        in cases where that can validly be done.  */
    520 
     530        // Modify the results slightly to make them prettier in cases where that can validly be done.
    521531        shift_boundaries();
    522532
    523         /* Get the results of comparison in the form of a chain
    524        of `struct change's -- an edit script.  */
     533        // Get the results of comparison in the form of a chain of `struct change's -- an edit script.
    525534        return bld.build_script(
    526535                filevec[0].changedFlag,
     
    529538                filevec[1].bufferedLines
    530539        );
    531 
    532540    }
    533541
     
    555563        public final int line1;
    556564
    557         /** Cons an additional entry onto the front of an edit script OLD.
    558        LINE0 and LINE1 are the first affected lines in the two files (origin 0).
    559        DELETED is the number of lines deleted here from file 0.
    560        INSERTED is the number of lines inserted here in file 1.
    561 
    562        If DELETED is 0 then LINE0 is the number of the line before
    563        which the insertion was done; vice versa for INSERTED and LINE1.  */
     565        /**
     566         * Cons an additional entry onto the front of an edit script OLD.
     567         * LINE0 and LINE1 are the first affected lines in the two files (origin 0).
     568         * DELETED is the number of lines deleted here from file 0.
     569         * INSERTED is the number of lines inserted here in file 1.
     570         *
     571         * If DELETED is 0 then LINE0 is the number of the line before
     572         * which the insertion was done; vice versa for INSERTED and LINE1.
     573         * @param line0 first affected lines in the two files (origin 0)
     574         * @param line1 first affected lines in the two files (origin 0)
     575         * @param deleted the number of lines deleted here from file 0
     576         * @param inserted the number of lines inserted here in file 1
     577         * @param old edit script
     578         */
    564579        public Change(int line0, int line1, int deleted, int inserted, Change old) {
    565580            this.line0 = line0;
     
    573588         * Returns the number of insertions and deletions of this change as well as
    574589         * (recursively) the changes linked via {@link #link}.
     590         * @return recursive number of insertions and deletions
    575591         */
    576592        public int getTotalNumberOfChanges() {
     
    585601    }
    586602
    587     /** Data on one input file being compared.
     603    /**
     604     * Data on one input file being compared.
    588605     */
    589606    class FileData {
     
    591608        /** Allocate changed array for the results of comparison.  */
    592609        void clear() {
    593             /* Allocate a flag for each line of each file, saying whether that line
    594                is an insertion or deletion.
    595                Allocate an extra element, always zero, at each end of each vector.
    596              */
     610            // Allocate a flag for each line of each file, saying whether that line is an insertion or deletion.
     611            // Allocate an extra element, always zero, at each end of each vector.
    597612            changedFlag = new boolean[bufferedLines + 2];
    598613        }
    599614
    600         /** Return equiv_count[I] as the number of lines in this file
    601          that fall in equivalence class I.
    602          @return the array of equivalence class counts.
     615        /**
     616         * Return equiv_count[I] as the number of lines in this file that fall in equivalence class I.
     617         * @return the array of equivalence class counts.
    603618         */
    604619        int[] equivCount() {
     
    610625        }
    611626
    612         /** Discard lines that have no matches in another file.
    613 
    614        A line which is discarded will not be considered by the actual
    615        comparison algorithm; it will be as if that line were not in the file.
    616        The file's `realindexes' table maps virtual line numbers
    617        (which don't count the discarded lines) into real line numbers;
    618        this is how the actual comparison algorithm produces results
    619        that are comprehensible when the discarded lines are counted.
    620 <p>
    621        When we discard a line, we also mark it as a deletion or insertion
    622        so that it will be printed in the output.
    623       @param f the other file
     627        /**
     628         * Discard lines that have no matches in another file.
     629         *
     630         * A line which is discarded will not be considered by the actual comparison algorithm;
     631         * it will be as if that line were not in the file.
     632         * The file's `realindexes' table maps virtual line numbers
     633         * (which don't count the discarded lines) into real line numbers;
     634         * this is how the actual comparison algorithm produces results
     635         * that are comprehensible when the discarded lines are counted.
     636         * <p>
     637         * When we discard a line, we also mark it as a deletion or insertion so that it will be printed in the output.
     638         * @param f the other file
    624639         */
    625640        void discard_confusing_lines(FileData f) {
    626641            clear();
    627             /* Set up table of which lines are going to be discarded. */
     642            // Set up table of which lines are going to be discarded.
    628643            final byte[] discarded = discardable(f.equivCount());
    629644
    630             /* Don't really discard the provisional lines except when they occur
    631        in a run of discardables, with nonprovisionals at the beginning
    632        and end.  */
     645            // Don't really discard the provisional lines except when they occur in a run of discardables,
     646            // with nonprovisionals at the beginning and end.
    633647            filterDiscards(discarded);
    634648
    635             /* Actually discard the lines. */
     649            // Actually discard the lines.
    636650            discard(discarded);
    637651        }
     
    674688        /**
    675689         * Don't really discard the provisional lines except when they occur
    676          * in a run of discardables, with nonprovisionals at the beginning
    677          * and end.
     690         * in a run of discardables, with nonprovisionals at the beginning and end.
     691         * @param discards discards
    678692         */
    679693        private void filterDiscards(final byte[] discards) {
  • trunk/src/org/openstreetmap/josm/tools/GBC.java

    r8911 r9231  
    124124    /**
    125125     * Sets the constraint's {@code gridx}, {@code gridy}.
     126     * @param gridx cell containing the leading edge of the component's display area
     127     * @param gridy cell at the top of the component's display area
    126128     * @return This constraint for chaining.
    127129     * @see #gridx
     
    136138    /**
    137139     * Sets the constraint's {@code gridwidth}, {@code gridheight}.
     140     * @param gridwidth number of cells in a row for the component's display area
     141     * @param gridheight number of cells in a column for the component's display area
    138142     * @return This constraint for chaining.
    139143     * @see #gridwidth
     
    148152    /**
    149153     * Sets the constraint's {@code gridwidth}.
     154     * @param gridwidth number of cells in a row for the component's display area
    150155     * @return This constraint for chaining.
    151156     * @see #gridwidth
     
    160165     *
    161166     * Is equivalent to {@code std().grid(gridx, gridy)}
     167     * @param gridx cell containing the leading edge of the component's display area
     168     * @param gridy cell at the top of the component's display area
    162169     * @return A standard constraint.
    163170     * @see #std()
     
    169176        return std().grid(gridx, gridy);
    170177    }
    171 
    172178}
  • trunk/src/org/openstreetmap/josm/tools/Geometry.java

    r9108 r9231  
    258258
    259259    /**
    260      * Finds the intersection of two line segments
     260     * Finds the intersection of two line segments.
     261     * @param p1 the coordinates of the start point of the first specified line segment
     262     * @param p2 the coordinates of the end point of the first specified line segment
     263     * @param p3 the coordinates of the start point of the second specified line segment
     264     * @param p4 the coordinates of the end point of the second specified line segment
    261265     * @return EastNorth null if no intersection was found, the EastNorth coordinates of the intersection otherwise
    262266     */
  • trunk/src/org/openstreetmap/josm/tools/Shortcut.java

    r9059 r9231  
    123123
    124124    /**
    125      * FOR PREF PANE ONLY
     125     * FOR PREF PANE ONLY.<p>
     126     * Sets the modifiers that are used.
     127     * @param assignedModifier assigned modifier
    126128     */
    127129    public void setAssignedModifier(int assignedModifier) {
     
    130132
    131133    /**
    132      * FOR PREF PANE ONLY
     134     * FOR PREF PANE ONLY.<p>
     135     * Sets the key that actually is used.
     136     * @param assignedKey assigned key
    133137     */
    134138    public void setAssignedKey(int assignedKey) {
     
    137141
    138142    /**
    139      * FOR PREF PANE ONLY
     143     * FOR PREF PANE ONLY.<p>
     144     * Sets whether the user has changed this shortcut.
     145     * @param assignedUser {@code true} if the user has changed this shortcut
    140146     */
    141147    public void setAssignedUser(boolean assignedUser) {
     
    202208    /**
    203209     * use this to set a menu's mnemonic
     210     * @param menu menu
    204211     */
    205212    public void setMnemonic(JMenu menu) {
     
    211218    /**
    212219     * use this to set a buttons's mnemonic
     220     * @param button button
    213221     */
    214222    public void setMnemonic(AbstractButton button) {
     
    220228    /**
    221229     * Sets the mnemonic key on a text component.
     230     * @param component component
    222231     */
    223232    public void setFocusAccelerator(JTextComponent component) {
     
    229238    /**
    230239     * use this to set a actions's accelerator
     240     * @param action action
    231241     */
    232242    public void setAccelerator(AbstractAction action) {
  • trunk/src/org/openstreetmap/josm/tools/Utils.java

    r9217 r9231  
    7777public final class Utils {
    7878
     79    /** Pattern matching white spaces */
    7980    public static final Pattern WHITE_SPACES_PATTERN = Pattern.compile("\\s+");
    8081
     
    311312     * convert float range 0 &lt;= x &lt;= 1 to integer range 0..255
    312313     * when dealing with colors and color alpha value
     314     * @param val float value between 0 and 1
    313315     * @return null if val is null, the corresponding int if val is in the
    314316     *         range 0...1. If val is outside that range, return 255
     
    336338    }
    337339
     340    /**
     341     * Returns the complementary color of {@code clr}.
     342     * @param clr the color to complement
     343     * @return the complementary color of {@code clr}
     344     */
    338345    public static Color complement(Color clr) {
    339346        return new Color(255 - clr.getRed(), 255 - clr.getGreen(), 255 - clr.getBlue(), clr.getAlpha());
Note: See TracChangeset for help on using the changeset viewer.