Changeset 5275 in josm


Ignore:
Timestamp:
Jun 9, 2012 8:03:41 PM (12 months 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.