Changeset 5275 in josm for trunk/src/org/openstreetmap


Ignore:
Timestamp:
2012-06-09T20:03:41+02:00 (12 years ago)
Author:
bastiK
Message:

doc improvements

Location:
trunk/src/org/openstreetmap/josm
Files:
16 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/org/openstreetmap/josm/actions/DeleteAction.java

    r4982 r5275  
    22package org.openstreetmap.josm.actions;
    33
     4import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
    45import static org.openstreetmap.josm.tools.I18n.tr;
    5 import static org.openstreetmap.josm.gui.help.HelpUtil.ht;
    66
    77import java.awt.event.ActionEvent;

  • trunk/src/org/openstreetmap/josm/actions/JosmAction.java

    r5266 r5275  
    1515import org.openstreetmap.josm.data.osm.OsmPrimitive;
    1616import org.openstreetmap.josm.gui.MapView;
     17import org.openstreetmap.josm.gui.MapView.LayerChangeListener;
    1718import org.openstreetmap.josm.gui.layer.Layer;
    1819import org.openstreetmap.josm.gui.layer.OsmDataLayer;
    … …  
    2526 *
    2627 * A JosmAction is a {@link LayerChangeListener} and a {@link SelectionChangedListener}. Upon
    27  * a layer change event or a selection change event it invokes {@link #updateEnabled()}.
    28  * Subclasses can override {@link #updateEnabled()} in order to update the {@link #isEnabled()}-state
     28 * a layer change event or a selection change event it invokes {@link #updateEnabledState()}.
     29 * Subclasses can override {@link #updateEnabledState()} in order to update the {@link #isEnabled()}-state
    2930 * of a JosmAction depending on the {@link #getCurrentDataSet()} and the current layers
    3031 * (see also {@link #getEditLayer()}).

  • trunk/src/org/openstreetmap/josm/actions/PasteTagsAction.java

    r5266 r5275  
    11// License: GPL. Copyright 2007 by Immanuel Scholz and others
    2 // Author: David Earl
    32package org.openstreetmap.josm.actions;
    43
    … …  
    2928import org.openstreetmap.josm.tools.Shortcut;
    3029
     30/**
     31 * Action, to paste all tags from one primitive to another.
     32 *
     33 * It will take the primitive from the copy-paste buffer an apply all its tags
     34 * to the selected primitive(s).
     35 *
     36 * @author David Earl
     37 */
    3138public final class PasteTagsAction extends JosmAction implements PasteBufferChangedListener {
    3239
    … …  
    5461         * Replies true if the source for tag pasting is heterogeneous, i.e. if it doesn't consist of
    5562         * {@link OsmPrimitive}s of exactly one type
    56          *
    57          * @return
    5863         */
    5964        protected boolean isHeteogeneousSource() {
    … …  
    130135
    131136        /**
    132          * Pastes the tags from a homogeneous source (i.e. the {@link Main#pasteBuffer}s selection consisting
    133          * of one type of {@link OsmPrimitive}s only.
     137         * Pastes the tags from a homogeneous source (the {@link Main#pasteBuffer}s selection consisting
     138         * of one type of {@link OsmPrimitive}s only).
    134139         *
    135140         * Tags from a homogeneous source can be pasted to a heterogeneous target. All target primitives,
    136141         * regardless of their type, receive the same tags.
    137          *
    138          * @param targets the collection of target primitives
    139142         */
    140143        protected void pasteFromHomogeneousSource() {
    … …  
    166169
    167170        /**
    168          * Replies true if there is at least one primitive of type <code>type</code> in the collection
    169          * <code>selection</code>
    170          *
    171          * @param <T>
    172          * @param selection  the collection of primitives
     171         * Replies true if there is at least one primitive of type <code>type</code>
     172         * is in the target collection
     173         *
     174         * @param <T>
    173175         * @param type  the type to look for
    174176         * @return true if there is at least one primitive of type <code>type</code> in the collection
    … …  
    199201         * Pastes the tags in the current selection of the paste buffer to a set of target
    200202         * primitives.
    201          *
    202          * @param targets the collection of target primitives
    203203         */
    204204        protected void pasteFromHeterogeneousSource() {

  • trunk/src/org/openstreetmap/josm/actions/downloadtasks/PostDownloadHandler.java

    r5149 r5275  
    3636     * constructor
    3737     * @param task the asynchronous download task
    38      * @param future the future on which the completion of the download task can be synchronized
     38     * @param futures the futures on which the completion of the download task can be synchronized
    3939     */
    4040    public PostDownloadHandler(DownloadTask task, Future<?> ... futures) {
    … …  
    5050     * constructor
    5151     * @param task the asynchronous download task
    52      * @param future the future on which the completion of the download task can be synchronized
     52     * @param futures the futures on which the completion of the download task can be synchronized
    5353     */
    5454    public PostDownloadHandler(DownloadTask task, List<Future<?>> futures) {

  • trunk/src/org/openstreetmap/josm/actions/mapmode/DeleteAction.java

    r5266 r5275  
    3333
    3434/**
    35  * An action that enables the user to delete nodes and other objects.
     35 * A map mode that enables the user to delete nodes and other objects.
    3636 *
    3737 * The user can click on an object, which gets deleted if possible. When Ctrl is
    … …  
    4343 *
    4444 * If the user enters the mapmode and any object is selected, all selected
    45  * objects that can be deleted will.
     45 * objects are deleted, if possible.
    4646 *
    4747 * @author imi
    … …  
    162162    /**
    163163     * Listen to mouse move to be able to update the cursor (and highlights)
    164      * @param MouseEvent The mouse event that has been captured
     164     * @param e The mouse event that has been captured
    165165     */
    166166    @Override public void mouseMoved(MouseEvent e) {
    … …  
    256256     * highlights
    257257     *
    258      * @param MouseEvent
    259      * @param int modifiers
     258     * @param e
     259     * @param modifiers
    260260     */
    261261    private void updateCursor(MouseEvent e, int modifiers) {
    … …  
    330330
    331331    /**
    332      * Deletes the relation in the context of the given layer. Also notifies
    333      * {@link RelationDialogManager} and {@link OsmDataLayer#fireDataChange()} events.
     332     * Deletes the relation in the context of the given layer.
    334333     *
    335334     * @param layer the layer in whose context the relation is deleted. Must not be null.
    … …  
    385384     * that should be deleted but does not actually delete them.
    386385     * @param e MouseEvent from which modifiers and position are taken
    387      * @param int modifiers For explanation: @see updateCursor
     386     * @param modifiers For explanation: @see updateCursor
    388387     * @param silet Set to true if the user should not be bugged with additional
    389388     *        dialogs

  • trunk/src/org/openstreetmap/josm/gui/ExceptionDialogUtil.java

    r5266 r5275  
    1414
    1515import org.openstreetmap.josm.Main;
     16import org.openstreetmap.josm.data.osm.OsmPrimitive;
    1617import org.openstreetmap.josm.io.ChangesetClosedException;
    1718import org.openstreetmap.josm.io.IllegalDataException;

  • trunk/src/org/openstreetmap/josm/gui/ExtendedDialog.java

    r5266 r5275  
    4242 * General configurable dialog window.
    4343 *
    44  * If dialog is modal, you can use getValue() to retrieve the
     44 * If dialog is modal, you can use {@link #getValue()} to retrieve the
    4545 * button index. Note that the user can close the dialog
    4646 * by other means. This is usually equivalent to cancel action.
    4747 *
    48  * For non-modal dialogs, buttonAction(int) can be overridden.
     48 * For non-modal dialogs, {@link #buttonAction(int, ActionEvent)} can be overridden.
    4949 *
    5050 * There are various options, see below.
    5151 *
    5252 * Note: The button indices are counted from 1 and upwards.
    53  * So for getValue(), setDefaultButton(int) and setCancelButton(int) the
    54  * first button has index 1.
     53 * So for {@link #getValue()}, {@link #setDefaultButton(int)} and
     54 * {@link #setCancelButton} the first button has index 1.
    5555 *
    5656 * Simple example:
    57  * <code>
     57 * <pre>
    5858 *  ExtendedDialog ed = new ExtendedDialog(
    5959 *          Main.parent, tr("Dialog Title"),
    … …  
    6666 *      // proceed...
    6767 *  }
    68  * </code>
     68 * </pre>
    6969 */
    7070public class ExtendedDialog extends JDialog {
    … …  
    171171
    172172    /**
    173      * Allows decorating the buttons with tooltips. Expects an String[] with translated
    174      * tooltip texts.
     173     * Allows decorating the buttons with tooltips. Expects a String array with
     174     * translated tooltip texts.
    175175     *
    176176     * @param toolTipTexts the tool tip texts. Ignored, if null.
    … …  
    224224    /**
    225225     * Decorate the dialog with an icon that is shown on the left part of
    226      * the window area. (Similar to how it is done in JOptionPane)
     226     * the window area. (Similar to how it is done in {@link JOptionPane})
    227227     */
    228228    public ExtendedDialog setIcon(Icon icon) {
    … …  
    232232
    233233    /**
    234      * Convenience method to allow values that would be accepted by JOptionPane as messageType.
     234     * Convenience method to allow values that would be accepted by {@link JOptionPane} as messageType.
    235235     */
    236236    public ExtendedDialog setIcon(int messageType) {
    … …  
    253253    /**
    254254     * Show the dialog to the user. Call this after you have set all options
    255      * for the dialog. You can retrieve the result using <code>getValue</code>
     255     * for the dialog. You can retrieve the result using {@link #getValue()}.
    256256     */
    257257    public ExtendedDialog showDialog() {
    … …  
    273273
    274274    /**
    275      * @return int * The selected button. The count starts with 1.
    276      *             * A return value of ExtendedDialog.DialogClosedOtherwise means the dialog has been closed otherwise.
     275     * Retrieve the user choice after the dialog has been closed.
     276     *
     277     * @return <ul> <li>The selected button. The count starts with 1.</li>
     278     *              <li>A return value of {@link #DialogClosedOtherwise} means the dialog has been closed otherwise.</li>
     279     *         </ul>
    277280     */
    278281    public int getValue() {
    … …  
    283286
    284287    /**
    285      * This is called by showDialog().
     288     * This is called by {@link #showDialog()}.
    286289     * Only invoke from outside if you need to modify the contentPane
    287290     */
    … …  
    402405    /**
    403406     * This gets performed whenever a button is clicked or activated
     407     * @param buttonIndex the button index (first index is 0)
    404408     * @param evt the button event
    405409     */
    … …  
    574578    /**
    575579     * This function checks the state of the "Do not show again" checkbox and
    576      * writes the corresponding pref
     580     * writes the corresponding pref.
    577581     */
    578582    private void toggleSaveState() {

  • trunk/src/org/openstreetmap/josm/gui/FileDrop.java

    r3710 r5275  
    134134     *
    135135     * @param out PrintStream to record debugging info or null for no debugging.
    136      * @param out
    137136     * @param c Component on which files will be dropped.
    138137     * @param listener Listens for <tt>filesDropped</tt>.
    … …  
    161160     *
    162161     * @param out PrintStream to record debugging info or null for no debugging.
    163      * @param out
    164162     * @param c Component on which files will be dropped.
    165163     * @param recursive Recursively set children as drop targets.

  • trunk/src/org/openstreetmap/josm/gui/dialogs/LayerListDialog.java

    r5266 r5275  
    4242import javax.swing.event.ChangeEvent;
    4343import javax.swing.event.ChangeListener;
     44import javax.swing.event.ListDataEvent;
    4445import javax.swing.event.ListSelectionEvent;
    4546import javax.swing.event.ListSelectionListener;

  • trunk/src/org/openstreetmap/josm/gui/layer/OsmDataLayer.java

    r5233 r5275  
    8484
    8585/**
    86  * A layer holding data from a specific dataset.
     86 * A layer that holds OSM data from a specific dataset.
    8787 * The data can be fully edited.
    8888 *

  • trunk/src/org/openstreetmap/josm/gui/mappaint/StyleSource.java

    r5219 r5275  
    8989        else
    9090            return ImageProvider.overlay(getSourceIcon(),
    91                     "dialogs/mappaint/error_small",
     91                    ImageProvider.get("dialogs/mappaint/error_small"),
    9292                    ImageProvider.OverlayPosition.SOUTHEAST);
    9393    }

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

    r3894 r5275  
    9898    /**
    9999     * Specifies how to distribute extra horizontal space.
    100      * @param weidhtx   Weight in horizontal direction
     100     * @param weightx   Weight in horizontal direction
    101101     * @param weighty   Weight in vertical direction
    102102     * @return This constraint for chaining.
    … …  
    114114     * @param y If higher than 0, this will be a vertical glue with y as minimum
    115115     *      vertical strut.
     116     * @return the glue component
    116117     */
    117118    public static Component glue(int x, int y) {

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

    r5266 r5275  
    3232
    3333    /**
    34      * Will find all intersection and add nodes there for list of given ways. Handles self-intersections too.
    35      * And make commands to add the intersection points to ways.
    36      * @param List<Way> - a list of ways to test
    37      * @return ArrayList<Node> List of new nodes
     34     * Will find all intersection and add nodes there for list of given ways.
     35     * Handles self-intersections too.
     36     * And makes commands to add the intersection points to ways.
     37     *
    3838     * Prerequisite: no two nodes have the same coordinates.
     39     *
     40     * @param ways  a list of ways to test
     41     * @param test  if false, do not build list of Commands, just return nodes
     42     * @param cmds  list of commands, typically empty when handed to this method.
     43     *              Will be filled with commands that add intersection nodes to
     44     *              the ways.
     45     * @return list of new nodes
    3946     */
    4047    public static Set<Node> addIntersections(List<Way> ways, boolean test, List<Command> cmds) {
    … …  
    472479
    473480    /**
    474      * returns area of a closed way in square meters
     481     * Returns area of a closed way in square meters.
    475482     * (approximate(?), but should be OK for small areas)
     483     *
     484     * Relies on the current projection: Works correctly, when
     485     * one unit in projected coordinates corresponds to one meter.
     486     * This is true for most projections, but not for WGS84 and
     487     * Mercator (EPSG:3857).
     488     *
     489     * @param way Way to measure, should be closed (first node is the same as last node)
     490     * @return area of the closed way.
    476491     */
    477492    public static double closedWayArea(Way way) {
    … …  
    532547     * If the area is negative the way is ordered in a clockwise direction.
    533548     *
     549     * See http://paulbourke.net/geometry/polyarea/
     550     *
    534551     * @param w the way to be checked.
    535552     * @return true if and only if way is oriented clockwise.
    536553     * @throws IllegalArgumentException if way is not closed (see {@link Way#isClosed}).
    537      * @see http://paulbourke.net/geometry/polyarea/
    538554     */
    539555    public static boolean isClockwise(Way w) {

  • trunk/src/org/openstreetmap/josm/tools/ImageProvider.java

    r5056 r5275  
    115115
    116116    /**
    117      * @param subdir    Subdirectory the image lies in.
    118      * @param name      The name of the image. If it does not end with '.png' or '.svg',
     117     * @param subdir    subdirectory the image lies in
     118     * @param name      the name of the image. If it does not end with '.png' or '.svg',
    119119     *                  both extensions are tried.
    120120     */
    … …  
    137137
    138138    /**
    139      * An id used for caching. Id is not used for cache if name starts with http://. (URL is unique anyway.)
     139     * Set an id used for caching.
     140     * If name starts with <tt>http://</tt> Id is not used for the cache.
     141     * (A URL is unique anyway.)
    140142     */
    141143    public ImageProvider setId(String id) {
    … …  
    145147
    146148    /**
    147      * A zip file where the image is located.
     149     * Specify a zip file where the image is located.
     150     *
     151     * (optional)
    148152     */
    149153    public ImageProvider setArchive(File archive) {
    … …  
    153157
    154158    /**
    155      * The dimensions of the image.
     159     * Set the dimensions of the image.
    156160     *
    157161     * If not specified, the original size of the image is used.
    … …  
    166170
    167171    /**
    168      * see setSize
     172     * @see #setSize
    169173     */
    170174    public ImageProvider setWidth(int width) {
    … …  
    174178
    175179    /**
    176      * see setSize
     180     * @see #setSize
    177181     */
    178182    public ImageProvider setHeight(int height) {
    … …  
    182186
    183187    /**
    184      * The maximum size of the image.
     188     * Limit the maximum size of the image.
    185189     *
    186190     * It will shrink the image if necessary, but keep the aspect ratio.
    … …  
    196200
    197201    /**
    198      * see setMaxSize
     202     * @see #setMaxSize
    199203     */
    200204    public ImageProvider setMaxWidth(int maxWidth) {
    … …  
    204208
    205209    /**
    206      * see setMaxSize
     210     * @see #setMaxSize
    207211     */
    208212    public ImageProvider setMaxHeight(int maxHeight) {
    … …  
    212216
    213217    /**
    214      * The image URL comes from user data and the image may be missing.
    215      *
    216      * Set true, if JOSM should *not* throw a RuntimeException in case the image cannot be located.
     218     * Decide, if an exception should be thrown, when the image cannot be located.
     219     *
     220     * Set to true, when the image URL comes from user data and the image may be missing.
     221     *
     222     * @param optional true, if JOSM should <b>not</b> throw a RuntimeException
     223     * in case the image cannot be located.
     224     * @return the current object, for convenience
    217225     */
    218226    public ImageProvider setOptional(boolean optional) {
    … …  
    241249    /**
    242250     * Execute the image request.
     251     * @return the requested image or null if the request failed
    243252     */
    244253    public ImageIcon get() {
    … …  
    267276     * asynchronously.
    268277     *
    269      * @param callback is called, when the image is ready. This can happen
    270      * before the call to getInBackground returns or it may be invoked some
    271      * time (seconds) later.
    272      * If no image is available, a null value is returned to callback (just
    273      * like ImageProvider.get).
     278     * @param callback a callback. It is called, when the image is ready.
     279     * This can happen before the call to this method returns or it may be
     280     * invoked some time (seconds) later. If no image is available, a null
     281     * value is returned to callback (just like {@link #get}).
    274282     */
    275283    public void getInBackground(final ImageCallback callback) {
    … …  
    290298
    291299    /**
    292      * Return an image from the specified location. Throws a RuntimeException if
    293      * the image cannot be located.
    294      *
    295      * @param subdir The position of the directory, e.g. 'layer'
    296      * @param name The icons name (with or without '.png' or '.svg' extension)
     300     * Load an image with a given file name.
     301     *
     302     * @param subdir subdirectory the image lies in
     303     * @param name The icon name (base name with or without '.png' or '.svg' extension)
    297304     * @return The requested Image.
     305     * @throws RuntimeException if the image cannot be located
    298306     */
    299307    public static ImageIcon get(String subdir, String name) {
    … …  
    301309    }
    302310
     311    /**
     312     * @see #get(java.lang.String, java.lang.String)
     313     */
    303314    public static ImageIcon get(String name) {
    304315        return new ImageProvider(name).get();
    305316    }
    306317
     318    /**
     319     * Load an image with a given file name, but do not throw an exception
     320     * when the image cannot be found.
     321     * @see #get(java.lang.String, java.lang.String)
     322     */
     323    public static ImageIcon getIfAvailable(String subdir, String name) {
     324        return new ImageProvider(subdir, name).setOptional(true).get();
     325    }
     326
     327    /**
     328     * @see #getIfAvailable(java.lang.String, java.lang.String)
     329     */
    307330    public static ImageIcon getIfAvailable(String name) {
    308331        return new ImageProvider(name).setOptional(true).get();
    309     }
    310 
    311     public static ImageIcon getIfAvailable(String subdir, String name) {
    312         return new ImageProvider(subdir, name).setOptional(true).get();
    313332    }
    314333
    … …  
    691710        ImageIcon img = get("cursor", name);
    692711        if (overlay != null) {
    693             img = overlay(img, "cursor/modifier/" + overlay, OverlayPosition.SOUTHEAST);
     712            img = overlay(img, ImageProvider.get("cursor/modifier/" + overlay), OverlayPosition.SOUTHEAST);
    694713        }
    695714        Cursor c = Toolkit.getDefaultToolkit().createCustomCursor(img.getImage(),
    … …  
    698717    }
    699718
    700     /**
     719    @Deprecated
     720    public static ImageIcon overlay(Icon ground, String overlayImage, OverlayPosition pos) {
     721        return overlay(ground, ImageProvider.get(overlayImage), pos);
     722    }
     723
     724    /**
     725     * Decorate one icon with an overlay icon.
     726     *
     727     * @param ground the base image
     728     * @param overlay the overlay image (can be smaller than the base image)
     729     * @param pos position of the overlay image inside the base image (positioned
     730     * in one of the corners)
    701731     * @return an icon that represent the overlay of the two given icons. The second icon is layed
    702732     * on the first relative to the given position.
    703733     */
    704     public static ImageIcon overlay(Icon ground, String overlayImage, OverlayPosition pos) {
    705         return overlay(ground, ImageProvider.get(overlayImage), pos);
    706     }
    707 
    708734    public static ImageIcon overlay(Icon ground, Icon overlay, OverlayPosition pos) {
    709735        GraphicsConfiguration conf = GraphicsEnvironment.getLocalGraphicsEnvironment().getDefaultScreenDevice()
    … …  
    739765    }
    740766
    741     /*
    742      * from: http://www.jidesoft.com/blog/2008/02/29/rotate-an-icon-in-java/ License:
    743      * "feel free to use"
    744      */
     767    /** 90 degrees in radians units */
    745768    final static double DEGREE_90 = 90.0 * Math.PI / 180.0;
    746769
    … …  
    750773     * @param c The component to get properties useful for painting, e.g. the foreground or
    751774     * background color.
    752      * @param icon the image to be rotated.
     775     * @param img the image to be rotated.
    753776     * @param rotatedAngle the rotated angle, in degree, clockwise. It could be any double but we
    754777     * will mod it with 360 before using it.
    … …  
    811834     * @return the icon
    812835     */
    813     public static ImageIcon get(OsmPrimitiveType type) throws IllegalArgumentException {
     836    public static ImageIcon get(OsmPrimitiveType type) {
    814837        CheckParameterUtil.ensureParameterNotNull(type, "type");
    815838        return get("data", type.getAPIName());

  • trunk/src/org/openstreetmap/josm/tools/LanguageInfo.java

    r5266 r5275  
    22package org.openstreetmap.josm.tools;
    33
     4import static org.openstreetmap.josm.tools.I18n.tr;
     5
    46import java.util.Locale;
    5 import static org.openstreetmap.josm.tools.I18n.tr;
    67
    78public class LanguageInfo {
    … …  
    8182     * In most cases JOSM and Java uses the same codes, but for some exceptions this is needed.
    8283     *
    83      * @param code the locale code.
     84     * @param localeName the locale code.
    8485     * @return the resulting locale
    8586     */

  • trunk/src/org/openstreetmap/josm/tools/WikiReader.java

    r5061 r5275  
    3333     * pathes etc..
    3434     *
    35      * @return
    3635     * @throws IOException Throws, if the page could not be loaded.
    3736     */
Note: See TracChangeset for help on using the changeset viewer.