Changeset 9231 in josm for trunk/src/org

Timestamp:

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

Author:

Don-vip

Message:

javadoc update

Location:

trunk/src/org/openstreetmap/josm

Files:

• actions/mapmode/ExtrudeAction.java (modified) (2 diffs)
• actions/mapmode/MapMode.java (modified) (3 diffs)
• actions/mapmode/SelectAction.java (modified) (3 diffs)
• command/MoveCommand.java (modified) (2 diffs)
• gui/dialogs/properties/SearchBasedRowFilter.java (modified) (1 diff)
• gui/layer/Layer.java (modified) (1 diff)
• gui/preferences/PreferenceSetting.java (modified) (1 diff)
• gui/preferences/imagery/ImageryPreference.java (modified) (1 diff)
• gui/preferences/map/MapPaintPreference.java (modified) (2 diffs)
• gui/progress/PleaseWaitProgressMonitor.java (modified) (3 diffs)
• gui/tagging/TagEditorModel.java (modified) (1 diff)
• gui/tagging/TagEditorPanel.java (modified) (4 diffs)
• gui/tagging/TagTable.java (modified) (2 diffs)
• gui/tagging/ac/AutoCompletionItemPriority.java (modified) (1 diff)
• gui/tagging/presets/TaggingPreset.java (modified) (1 diff)
• gui/tagging/presets/TaggingPresetMenu.java (modified) (1 diff)
• gui/tagging/presets/TaggingPresetSelector.java (modified) (1 diff)
• gui/tagging/presets/items/ComboMultiSelect.java (modified) (1 diff)
• gui/tagging/presets/items/Roles.java (modified) (1 diff)
• gui/util/AdjustmentSynchronizer.java (modified) (1 diff)
• gui/util/GuiHelper.java (modified) (1 diff)
• gui/util/TableHelper.java (modified) (1 diff)
• gui/widgets/AbstractTextComponentValidator.java (modified) (2 diffs)
• gui/widgets/MultiSplitLayout.java (modified) (6 diffs)
• gui/widgets/TextContextualPopupMenu.java (modified) (1 diff)
• io/FileImporter.java (modified) (3 diffs)
• io/GpxExporter.java (modified) (1 diff)
• io/GpxReader.java (modified) (3 diffs)
• io/GpxWriter.java (modified) (3 diffs)
• io/MultiFetchServerObjectReader.java (modified) (4 diffs)
• io/OsmReader.java (modified) (4 diffs)
• io/OsmServerBackreferenceReader.java (modified) (1 diff)
• io/OsmServerHistoryReader.java (modified) (1 diff)
• io/OsmServerWriter.java (modified) (1 diff)
• io/OsmWriter.java (modified) (2 diffs)
• io/UTFInputStreamReader.java (modified) (2 diffs)
• io/XmlWriter.java (modified) (2 diffs)
• io/remotecontrol/AddTagsDialog.java (modified) (2 diffs)
• io/remotecontrol/RequestProcessor.java (modified) (2 diffs)
• io/remotecontrol/handler/AddWayHandler.java (modified) (1 diff)
• io/session/SessionReader.java (modified) (1 diff)
• io/session/SessionWriter.java (modified) (2 diffs)
• plugins/Plugin.java (modified) (3 diffs)
• tools/CheckParameterUtil.java (modified) (1 diff)
• tools/CopyList.java (modified) (3 diffs)
• tools/Diff.java (modified) (14 diffs)
• tools/GBC.java (modified) (5 diffs)
• tools/Geometry.java (modified) (1 diff)
• tools/Shortcut.java (modified) (7 diffs)
• tools/Utils.java (modified) (3 diffs)

trunk/src/org/openstreetmap/josm/actions/mapmode/ExtrudeAction.java

@@ -909 +909 @@
      * For dual align, calculates positions of new nodes, aligning them to neighboring segments.
      * Elsewhere, just adds the vetor returned by calculateBestMovement to {@link #initialN1en},  {@link #initialN2en}.
+     * @param mouseEn mouse coordinates
      * @return best movement vector
      */
@@ -1109 +1110 @@
 
     /**
-     * Determines if from1-to1 and from2-to2 vertors directions are opposite
-     * @return true if from1-to1 and from2-to2 vertors directions are opposite
+     * Determines if from1-to1 and from2-to2 vectors directions are opposite
+     * @param from1 vector1 start
+     * @param to1 vector1 end
+     * @param from2 vector2 start
+     * @param to2 vector2 end
+     * @return true if from1-to1 and from2-to2 vectors directions are opposite
      */
     private static boolean isOppositeDirection(EastNorth from1, EastNorth to1, EastNorth from2, EastNorth to2) {

trunk/src/org/openstreetmap/josm/actions/mapmode/MapMode.java

@@ -18 +18 @@
 /**
  * A class implementing MapMode is able to be selected as an mode for map editing.
- * As example scrolling the map is a MapMode, connecting Nodes to new Ways
- * is another.
+ * As example scrolling the map is a MapMode, connecting Nodes to new Ways is another.
  *
  * MapModes should register/deregister all necessary listeners on the map's view control.
@@ -30 +29 @@
 
     /**
-     * Constructor for mapmodes without an menu
+     * Constructor for mapmodes without a menu
+     * @param name the action's text
+     * @param iconName icon filename in {@code mapmode} directory
+     * @param tooltip  a longer description of the action that will be displayed in the tooltip.
+     * @param shortcut a ready-created shortcut object or null if you don't want a shortcut.
      * @param mapFrame unused but kept for plugin compatibility. Can be {@code null}
+     * @param cursor cursor displayed when map mode is active
      */
     public MapMode(String name, String iconName, String tooltip, Shortcut shortcut, MapFrame mapFrame, Cursor cursor) {
@@ -40 +44 @@
 
     /**
-     * Constructor for mapmodes with an menu (no shortcut will be registered)
+     * Constructor for mapmodes with a menu (no shortcut will be registered)
+     * @param name the action's text
+     * @param iconName icon filename in {@code mapmode} directory
+     * @param tooltip  a longer description of the action that will be displayed in the tooltip.
      * @param mapFrame unused but kept for plugin compatibility. Can be {@code null}
+     * @param cursor cursor displayed when map mode is active
      */
     public MapMode(String name, String iconName, String tooltip, MapFrame mapFrame, Cursor cursor) {

trunk/src/org/openstreetmap/josm/actions/mapmode/SelectAction.java

@@ -887 +887 @@
      * key is pressed. If there is no such node, no action will be done and no error will be
      * reported. If there is, it will execute the merge and add it to the undo buffer.
+     * @param p mouse position
      */
     private void mergePrims(Point p) {
@@ -935 +936 @@
      * Tries to find a node to merge to when in move-merge mode for the current mouse
      * position. Either returns the node or null, if no suitable one is nearby.
+     * @param p mouse position
      * @return node to merge to, or null
      */
@@ -1261 +1263 @@
 
     /**
-     * @return o as collection of o's type.
+     * Returns {@code o} as collection of {@code o}'s type.
+     * @param o any object
+     * @return {@code o} as collection of {@code o}'s type.
      */
     protected static <T> Collection<T> asColl(T o) {

trunk/src/org/openstreetmap/josm/command/MoveCommand.java

@@ -139 +139 @@
     }
 
+    /**
+     * Move again to the specified coordinates.
+     * @param x X coordinate
+     * @param y Y coordinate
+     * @see #moveAgain
+     */
     public void moveAgainTo(double x, double y) {
         moveAgain(x - this.x, y - this.y);
@@ -144 +150 @@
 
     /**
-     * Change the displacement vector to have endpoint @param currentEN
-     * starting point is  startEN
+     * Change the displacement vector to have endpoint {@code currentEN}.
+     * starting point is startEN
+     * @param currentEN the new endpoint
      */
     public void applyVectorTo(EastNorth currentEN) {

trunk/src/org/openstreetmap/josm/gui/dialogs/properties/SearchBasedRowFilter.java

@@ -14 +14 @@
 /**
  * A {@link RowFilter} implementation which matches tags w.r.t. the specified filter's
- * {@link SearchCompiler.Match#match(org.openstreetmap.josm.data.osm.Tagged)} method.
+ * {@link org.openstreetmap.josm.actions.search.SearchCompiler.Match#match(org.openstreetmap.josm.data.osm.Tagged)} method.
  *
  * <p>An {@link javax.swing.RowFilter.Entry}'s column 0 is considered as key, and column 1 is considered as value.</p>

trunk/src/org/openstreetmap/josm/gui/layer/Layer.java

@@ -408 +408 @@
     /**
      * allows to check whether a projection is supported or not
+     * @param proj projection
      *
      * @return True if projection is supported for this layer

trunk/src/org/openstreetmap/josm/gui/preferences/PreferenceSetting.java

@@ -10 +10 @@
      * Add the GUI elements to the dialog. The elements should be initialized after
      * the current preferences.
+     * @param gui the preferences tab pane
      */
     void addGui(PreferenceTabbedPane gui);

trunk/src/org/openstreetmap/josm/gui/preferences/imagery/ImageryPreference.java

@@ -808 +808 @@
         /**
          * Constructs a new {@code OffsetBookmarksPanel}.
+         * @param gui the preferences tab pane
          */
         OffsetBookmarksPanel(final PreferenceTabbedPane gui) {

trunk/src/org/openstreetmap/josm/gui/preferences/map/MapPaintPreference.java

@@ -168 +168 @@
     }
 
+    /**
+     * Returns title from a source entry.
+     * @param entry source entry
+     * @return title
+     * @see MapCSSStyleSource#title
+     */
     public static String getTitleFromSourceEntry(SourceEntry entry) {
         try {
@@ -233 +239 @@
          * the new entries to the user-configured list. Remember the known URLs,
          * so an item that was deleted explicitly is not added again.
+         * @param list new defaults
+         * @return {@code true} if a change occurred
          */
         private boolean insertNewDefaults(List<SourceEntry> list) {

trunk/src/org/openstreetmap/josm/gui/progress/PleaseWaitProgressMonitor.java

@@ -108 +108 @@
     /**
      * Constructs a new {@code PleaseWaitProgressMonitor}.
+     * @param windowTitle window title
      */
     public PleaseWaitProgressMonitor(String windowTitle) {
@@ -116 +117 @@
     /**
      * Constructs a new {@code PleaseWaitProgressMonitor}.
+     * @param dialogParent component to get parent frame from
      */
     public PleaseWaitProgressMonitor(Component dialogParent) {
@@ -129 +131 @@
     /**
      * Constructs a new {@code PleaseWaitProgressMonitor}.
+     * @param dialogParent component to get parent frame from
+     * @param windowTitle window title
      */
     public PleaseWaitProgressMonitor(Component dialogParent, String windowTitle) {

trunk/src/org/openstreetmap/josm/gui/tagging/TagEditorModel.java

@@ -413 +413 @@
     /**
      * applies the current state of the tag editor model to a map of tags
+     * @param keepEmpty {@code true} to keep empty tags
      *
      * @return the map of key/value pairs

trunk/src/org/openstreetmap/josm/gui/tagging/TagEditorPanel.java

@@ -59 +59 @@
     }
 
+    /**
+     * Sets the next component to request focus after navigation (with tab or enter).
+     * @param nextFocusComponent next component to request focus after navigation (with tab or enter)
+     * @see TagTable#setNextFocusComponent
+     */
     public void setNextFocusComponent(Component nextFocusComponent) {
         tagTable.setNextFocusComponent(nextFocusComponent);
@@ -91 +96 @@
     }
 
+    /**
+     * Returns the paste action.
+     * @return the paste action
+     */
     public AbstractAction getPasteAction() {
         return tagTable.getPasteAction();
@@ -141 +150 @@
      * Creates a new tag editor panel. The editor model is created
      * internally and can be retrieved with {@link #getModel()}.
+     * @param presetHandler tagging preset handler
      */
     public TagEditorPanel(TaggingPresetHandler presetHandler) {
@@ -147 +157 @@
 
     /**
-     * Creates a new tag editor panel with a supplied model. If
-     * {@code model} is null, a new model is created.
+     * Creates a new tag editor panel with a supplied model. If {@code model} is null, a new model is created.
      *
      * @param model the tag editor model
+     * @param presetHandler tagging preset handler
      * @param maxCharacters maximum number of characters allowed, 0 for unlimited
      */

trunk/src/org/openstreetmap/josm/gui/tagging/TagTable.java

@@ -504 +504 @@
     }
 
+    /**
+     * Sets the next component to request focus after navigation (with tab or enter).
+     * @param nextFocusComponent next component to request focus after navigation (with tab or enter)
+     */
     public void setNextFocusComponent(Component nextFocusComponent) {
         this.nextFocusComponent = nextFocusComponent;
@@ -512 +516 @@
     }
 
-    public void  addOKAccelatorListener(KeyListener l) {
+    public void addOKAccelatorListener(KeyListener l) {
         addKeyListener(l);
         if (editor != null) {

trunk/src/org/openstreetmap/josm/gui/tagging/ac/AutoCompletionItemPriority.java

@@ -106 +106 @@
      * Merges two priorities.
      * The resulting priority is always >= the original ones.
+     * @param other other priority
      * @return the merged priority
      */

trunk/src/org/openstreetmap/josm/gui/tagging/presets/TaggingPreset.java

@@ -204 +204 @@
     /**
      * Called from the XML parser to set the types this preset affects.
+     * @param types comma-separated primitive types ("node", "way", "relation" or "closedway")
      * @throws SAXException if any SAX error occurs
+     * @see TaggingPresetType#fromString
      */
     public void setType(String types) throws SAXException {

trunk/src/org/openstreetmap/josm/gui/tagging/presets/TaggingPresetMenu.java

@@ -108 +108 @@
     /**
      * Sorts the menu items using the translated item text
+     * @param menu menu to sort
      */
     public static void sortMenu(JMenu menu) {

trunk/src/org/openstreetmap/josm/gui/tagging/presets/TaggingPresetSelector.java

@@ -215 +215 @@
     /**
      * Constructs a new {@code TaggingPresetSelector}.
+     * @param displayOnlyApplicable if {@code true} display "Show only applicable to selection" checkbox
+     * @param displaySearchInTags if {@code true} display "Search in tags" checkbox
      */
     public TaggingPresetSelector(boolean displayOnlyApplicable, boolean displaySearchInTags) {

trunk/src/org/openstreetmap/josm/gui/tagging/presets/items/ComboMultiSelect.java

@@ -258 +258 @@
      *      must be escaped within one entry
      * @param s the string
+     * @return splitted items
      */
     public static String[] splitEscaped(char delimiter, String s) {

trunk/src/org/openstreetmap/josm/gui/tagging/presets/items/Roles.java

@@ -68 +68 @@
         /**
          * Return either argument, the highest possible value or the lowest allowed value
+         * @param c count
+         * @return the highest possible value or the lowest allowed value
+         * @see #required
          */
         public long getValidCount(long c) {

trunk/src/org/openstreetmap/josm/gui/util/AdjustmentSynchronizer.java

@@ -72 +72 @@
 
     /**
-     * Sets whether adjustable participates in adjustment synchronization or not
+     * Sets whether {@code adjustable} participates in adjustment synchronization or not
      *
      * @param adjustable the adjustable
+     * @param isParticipating {@code true} if {@code adjustable} participates in adjustment synchronization
      */
     protected void setParticipatingInSynchronizedScrolling(Adjustable adjustable, boolean isParticipating) {

trunk/src/org/openstreetmap/josm/gui/util/GuiHelper.java

@@ -62 +62 @@
     /**
      * disable / enable a component and all its child components
+     * @param root component
+     * @param enabled enabled state
      */
     public static void setEnabledRec(Container root, boolean enabled) {

trunk/src/org/openstreetmap/josm/gui/util/TableHelper.java

@@ -20 +20 @@
      * adjust the preferred width of column col to the maximum preferred width of the cells
      * requires JTable.setAutoResizeMode(JTable.AUTO_RESIZE_OFF);
+     * @param tbl table
+     * @param col column index
+     * @param maxColumnWidth maximum column width
      */
     public static void adjustColumnWidth(JTable tbl, int col, int maxColumnWidth) {

trunk/src/org/openstreetmap/josm/gui/widgets/AbstractTextComponentValidator.java

@@ -92 +92 @@
      * Alternative constructor that allows to turn off the actionListener.
      * This can be useful if the enter key stroke needs to be forwarded to the default button in a dialog.
+     * @param tc text component
+     * @param addActionListener {@code true} to add the action listener
      */
     public AbstractTextComponentValidator(JTextComponent tc, boolean addActionListener) {
@@ -97 +99 @@
     }
 
+    /**
+     * Constructs a new {@code AbstractTextComponentValidator}.
+     * @param tc text component
+     * @param addFocusListener {@code true} to add the focus listener
+     * @param addDocumentListener {@code true} to add the document listener
+     * @param addActionListener {@code true} to add the action listener
+     */
     public AbstractTextComponentValidator(JTextComponent tc, boolean addFocusListener, boolean addDocumentListener, boolean addActionListener) {
         CheckParameterUtil.ensureParameterNotNull(tc, "tc");

trunk/src/org/openstreetmap/josm/gui/widgets/MultiSplitLayout.java

@@ -94 +94 @@
      *
      * #see setModel
+     * @param model model
      */
     public MultiSplitLayout(Node model) {
@@ -196 +197 @@
      * Split and Leaf nodes.  Typically this property is set to false
      * after the (MultiSplitPane) user has dragged a Divider.
+     * @param floatingDividers boolean value
      *
      * @see #getFloatingDividers
@@ -690 +692 @@
         private final transient Node node;
 
+        /**
+         * Constructs a new {@code InvalidLayoutException}.
+         * @param msg the detail message. The detail message is saved for later retrieval by the {@link #getMessage()} method.
+         * @param node node
+         */
         public InvalidLayoutException(String msg, Node node) {
             super(msg);
@@ -1234 +1241 @@
 
     /**
-     * A convenience method that converts a string to a
-     * MultiSplitLayout model (a tree of Nodes) using a
-     * a simple syntax.  Nodes are represented by
-     * parenthetical expressions whose first token
-     * is one of ROW/COLUMN/LEAF.  ROW and COLUMN specify
-     * horizontal and vertical Split nodes respectively,
-     * LEAF specifies a Leaf node.  A Leaf's name and
-     * weight can be specified with attributes,
+     * A convenience method that converts a string to a MultiSplitLayout model (a tree of Nodes) using a
+     * a simple syntax.  Nodes are represented by parenthetical expressions whose first token
+     * is one of ROW/COLUMN/LEAF.  ROW and COLUMN specify horizontal and vertical Split nodes respectively,
+     * LEAF specifies a Leaf node.  A Leaf's name and weight can be specified with attributes,
      * name=<i>myLeafName</i> weight=<i>myLeafWeight</i>.
-     * Similarly, a Split's weight can be specified with
-     * weight=<i>mySplitWeight</i>.
-     *
-     * <p> For example, the following expression generates
-     * a horizontal Split node with three children:
-     * the Leafs named left and right, and a Divider in
-     * between:
+     * Similarly, a Split's weight can be specified with weight=<i>mySplitWeight</i>.
+     *
+     * <p> For example, the following expression generates a horizontal Split node with three children:
+     * the Leafs named left and right, and a Divider in between:
      * <pre>
      * (ROW (LEAF name=left) (LEAF name=right weight=1.0))
      * </pre>
      *
-     * <p> Dividers should not be included in the string,
-     * they're added automatcially as needed.  Because
-     * Leaf nodes often only need to specify a name, one
-     * can specify a Leaf by just providing the name.
+     * <p> Dividers should not be included in the string, they're added automatcially as needed.  Because
+     * Leaf nodes often only need to specify a name, one can specify a Leaf by just providing the name.
      * The previous example can be written like this:
      * <pre>
@@ -1263 +1261 @@
      * </pre>
      *
-     * <p>Here's a more complex example.  One row with
-     * three elements, the first and last of which are columns
+     * <p>Here's a more complex example.  One row with three elements, the first and last of which are columns
      * with two leaves each:
      * <pre>
@@ -1272 +1269 @@
      * </pre>
      *
-     *
-     * <p> This syntax is not intended for archiving or
-     * configuration files .  It's just a convenience for
+     * <p> This syntax is not intended for archiving or configuration files .  It's just a convenience for
      * examples and tests.
+     * @param s model as string
      *
      * @return the Node root of a tree based on s.

trunk/src/org/openstreetmap/josm/gui/widgets/TextContextualPopupMenu.java

@@ -81 +81 @@
      * A menu can only be attached to a single component.
      * @param component The text component that will display the menu and handle its actions.
+     * @param undoRedo {@code true} if undo/redo must be supported
      * @return {@code this}
      * @see #detach()

trunk/src/org/openstreetmap/josm/io/FileImporter.java

@@ -19 +19 @@
 import org.openstreetmap.josm.gui.util.GuiHelper;
 
+/**
+ * Abstract file importer.
+ * @since 1637
+ */
 public abstract class FileImporter implements Comparable<FileImporter>, LayerChangeListener {
 
@@ -77 +81 @@
 
     /**
-     * Wrapper to give meaningful output if things go wrong.
+     * Wrapper to {@link #importData(File, ProgressMonitor)} to give meaningful output if things go wrong.
+     * @param f data file to import
+     * @param progressMonitor progress monitor
      * @return true if data import was successful
      */
@@ -121 +127 @@
     }
 
+    /**
+     * Wrapper to {@link #importData(List, ProgressMonitor)} to give meaningful output if things go wrong.
+     * @param files data files to import
+     * @param progressMonitor progress monitor
+     * @return true if data import was successful
+     */
     public boolean importDataHandleExceptions(List<File> files, ProgressMonitor progressMonitor) {
         try {

trunk/src/org/openstreetmap/josm/io/GpxExporter.java

@@ -248 +248 @@
     /**
      * Add all those listeners to handle the enable state of the fields.
+     * @param data GPX data
+     * @param author Author checkbox
+     * @param authorName Author name textfield
+     * @param email E-mail textfield
+     * @param copyright Copyright textfield
+     * @param predefined Predefined button
+     * @param copyrightYear Copyright year textfield
+     * @param nameLabel Name label
+     * @param emailLabel E-mail label
+     * @param copyrightLabel Copyright label
+     * @param copyrightYearLabel Copyright year label
+     * @param warning Warning label
      */
     private static void addDependencies(

trunk/src/org/openstreetmap/josm/io/GpxReader.java

@@ -499 +499 @@
         /**
          * convert url/urlname to link element (GPX 1.0 -> GPX 1.1).
+         * @param attr attributes
          */
         private void convertUrlToLink(Map<String, Object> attr) {
@@ -509 +510 @@
                 GpxLink link = new GpxLink(url);
                 link.text = urlname;
-                @SuppressWarnings({ "unchecked", "rawtypes" })
+                @SuppressWarnings("unchecked")
                 Collection<GpxLink> links = (Collection<GpxLink>) attr.get(META_LINKS);
                 links.add(link);
@@ -531 +532 @@
      * @throws IOException if an IO error occurs, e.g. the input stream is closed.
      */
-    @SuppressWarnings("resource")
     public GpxReader(InputStream source) throws IOException {
         Reader utf8stream = UTFInputStreamReader.create(source);

trunk/src/org/openstreetmap/josm/io/GpxWriter.java

@@ -248 +248 @@
      * if content not null, open tag, write encoded content, and close tag
      * else do nothing.
+     * @param tag GPX tag
+     * @param content content
      */
     private void simpleTag(String tag, String content) {
@@ -260 +262 @@
     /**
      * output link
+     * @param link link
      */
     private void gpxLink(GpxLink link) {
@@ -272 +275 @@
     /**
      * output a point
+     * @param pnt waypoint
+     * @param mode {@code WAY_POINT} for {@code wpt}, {@code ROUTE_POINT} for {@code rtept}, {@code TRACK_POINT} for {@code trkpt}
      */
     private void wayPoint(WayPoint pnt, int mode) {

trunk/src/org/openstreetmap/josm/io/MultiFetchServerObjectReader.java

@@ -299 +299 @@
      * @param type The primitive type. Must be one of {@link OsmPrimitiveType#NODE NODE}, {@link OsmPrimitiveType#WAY WAY},
      * {@link OsmPrimitiveType#RELATION RELATION}
+     * @param progressMonitor progress monitor
      * @throws OsmTransferException if an error occurs while communicating with the API server
      */
@@ -485 +486 @@
          * {@link OsmPrimitiveType#RELATION RELATION}
          * @param pkg the package of ids
+         * @param progressMonitor progress monitor
          * @return the {@link FetchResult} of this operation
          * @throws OsmTransferException if an error occurs while communicating with the API server
@@ -513 +515 @@
          * {@link OsmPrimitiveType#RELATION RELATION}
          * @param id the id
+         * @param progressMonitor progress monitor
          * @return the {@link DataSet} resulting of this operation
          * @throws OsmTransferException if an error occurs while communicating with the API server
@@ -544 +547 @@
          * {@link OsmPrimitiveType#RELATION RELATION}
          * @param pkg the set of ids
+         * @param progressMonitor progress monitor
          * @return the {@link FetchResult} of this operation
          * @throws OsmTransferException if an error occurs while communicating with the API server

trunk/src/org/openstreetmap/josm/io/OsmReader.java

@@ -57 +57 @@
     private static volatile List<OsmServerReadPostprocessor> postprocessors;
 
-    /** register a new postprocessor */
+    /** Register a new postprocessor.
+     * @param pp postprocessor
+     * @see #deregisterPostprocessor
+     */
     public static void registerPostprocessor(OsmServerReadPostprocessor pp) {
         if (postprocessors == null) {
@@ -65 +68 @@
     }
 
-    /** deregister a postprocessor previously registered with registerPostprocessor */
+    /**
+     * Deregister a postprocessor previously registered with {@link #registerPostprocessor}.
+     * @param pp postprocessor
+     * @see #registerPostprocessor
+     */
     public static void deregisterPostprocessor(OsmServerReadPostprocessor pp) {
         if (postprocessors != null) {
@@ -399 +406 @@
      * This is basically the same code as parseUnknown(), except for the warnings, which
      * are displayed for inner elements and not at top level.
+     * @param printWarning if {@code true}, a warning message will be printed if an unknown element is met
      * @throws XMLStreamException if there is an error processing the underlying XML source
      */
@@ -432 +440 @@
     /**
      * Read out the common attributes and put them into current OsmPrimitive.
+     * @param current primitive to update
      * @throws XMLStreamException if there is an error processing the underlying XML source
      */

trunk/src/org/openstreetmap/josm/io/OsmServerBackreferenceReader.java

@@ -148 +148 @@
      * Reads referring ways from the API server and replies them in a {@link DataSet}
      *
+     * @param progressMonitor progress monitor
      * @return the data set
      * @throws OsmTransferException if any error occurs during dialog with OSM API

trunk/src/org/openstreetmap/josm/io/OsmServerHistoryReader.java

@@ -50 +50 @@
     /**
      * Fetches the history from the OSM API and parses it
+     * @param progressMonitor progress monitor
      *
      * @return the data set with the parsed history data

trunk/src/org/openstreetmap/josm/io/OsmServerWriter.java

@@ -256 +256 @@
     /**
      * Calls all registered upload postprocessors.
+     * @param pm progress monitor
      */
     public void executePostprocessors(ProgressMonitor pm) {

trunk/src/org/openstreetmap/josm/io/OsmWriter.java

@@ -46 +46 @@
 
     /**
-     * Do not call this directly. Use OsmWriterFactory instead.
+     * Constructs a new {@code OsmWriter}.
+     * Do not call this directly. Use {@link OsmWriterFactory} instead.
+     * @param out print writer
+     * @param version OSM API version (0.6)
      */
     protected OsmWriter(PrintWriter out, boolean osmConform, String version) {
@@ -279 +282 @@
      * Add the common part as the form of the tag as well as the XML attributes
      * id, action, user, and visible.
+     * @param osm osm primitive
+     * @param tagname XML tag matching osm primitive (node, way, relation)
      */
     protected void addCommon(IPrimitive osm, String tagname) {

trunk/src/org/openstreetmap/josm/io/UTFInputStreamReader.java

@@ -15 +15 @@
     /**
      * Creates a new {@link InputStreamReader} from the {@link InputStream} with UTF-8 as default encoding.
+     * @param input input stream
      * @return A reader with the correct encoding. Starts to read after the BOM.
      * @throws IOException if any I/O error occurs
@@ -25 +26 @@
     /**
      * Creates a new {@link InputStreamReader} from the {@link InputStream}.
+     * @param input input stream
      * @param defaultEncoding Used, when no BOM was recognized. Can be null.
      * @return A reader with the correct encoding. Starts to read after the BOM.

trunk/src/org/openstreetmap/josm/io/XmlWriter.java

@@ -17 +17 @@
     protected final PrintWriter out;
 
+    /**
+     * Constructs a new {@code XmlWriter}.
+     * @param out print writer
+     */
     public XmlWriter(PrintWriter out) {
         this.out = out;
@@ -30 +34 @@
     }
 
+    /**
+     * Encode the given string in XML1.0 format.
+     * Optimized to fast pass strings that don't need encoding (normal case).
+     *
+     * @param unencoded the unencoded input string
+     * @return XML1.0 string
+     */
     public static String encode(String unencoded) {
         return encode(unencoded, false);

trunk/src/org/openstreetmap/josm/io/remotecontrol/AddTagsDialog.java

@@ -119 +119 @@
     /**
      * Constructs a new {@code AddTagsDialog}.
+     * @param tags tags to add
+     * @param senderName String for skipping confirmations. Use empty string for always confirmed adding.
+     * @param primitives OSM objects that will be modified
      */
     public AddTagsDialog(String[][] tags, String senderName, Collection<? extends OsmPrimitive> primitives) {
@@ -260 +263 @@
      * parse addtags parameters Example URL (part):
      * addtags=wikipedia:de%3DResidenzschloss Dresden|name:en%3DDresden Castle
+     * @param args request arguments
+     * @param sender is a string for skipping confirmations. Use empty string for always confirmed adding.
+     * @param primitives OSM objects that will be modified
      */
     public static void addTags(final Map<String, String> args, final String sender, final Collection<? extends OsmPrimitive> primitives) {

trunk/src/org/openstreetmap/josm/io/remotecontrol/RequestProcessor.java

@@ -301 +301 @@
      * @param out
      *            The writer where the error is written
+     * @param help
+     *            Optional HTML help content to display, can be null
      * @throws IOException
      *             If the error can not be written
@@ -323 +325 @@
      * @param out
      *            The writer where the error is written
+     * @param help
+     *            Optional HTML help content to display, can be null
      * @throws IOException
      *             If the error can not be written

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/AddWayHandler.java

@@ -122 +122 @@
      * Find the node with almost the same coords in dataset or in already added nodes
      * @param ll coordinates
+     * @param commands list of commands that will be modified if needed
      * @return node with almost the same coords
      * @since 5845
      */
-    Node findOrCreateNode(LatLon ll,  List<Command> commands) {
+    Node findOrCreateNode(LatLon ll, List<Command> commands) {
         Node nd = null;
 

trunk/src/org/openstreetmap/josm/io/session/SessionReader.java

@@ -145 +145 @@
          * Add a task, e.g. a message dialog, that should
          * be executed in EDT after all layers have been added.
+         * @param task task to run in EDT
          */
         public void addPostLayersTask(Runnable task) {

trunk/src/org/openstreetmap/josm/io/session/SessionWriter.java

@@ -65 +65 @@
      *
      * The exporter class must have a one-argument constructor with layerClass as formal parameter type.
+     * @param layerClass layer class
+     * @param exporter exporter for this layer class
      */
     public static void registerSessionLayerExporter(Class<? extends Layer> layerClass, Class<? extends SessionLayerExporter> exporter) {
@@ -95 +97 @@
      * @param active The index of active layer in {@code layers} (starts at 0). Ignored if set to -1
      * @param exporters The exporters to use to save layers
+     * @param dependencies layer dependencies
      * @param zip {@code true} if a joz archive has to be created, {@code false otherwise}
      * @since 6271

trunk/src/org/openstreetmap/josm/plugins/Plugin.java

@@ -101 +101 @@
      * Called in the download dialog to give the plugin a chance to modify the list
      * of bounding box selectors.
+     * @param list list of bounding box selectors
      */
     public void addDownloadSelection(List<DownloadSelection> list) {}
@@ -106 +107 @@
     /**
      * Copies the resource 'from' to the file in the plugin directory named 'to'.
+     * @param from source file
+     * @param to target file
      * @throws FileNotFoundException if the file exists but is a directory rather than a regular file,
      * does not exist but cannot be created, or cannot be opened for any other reason
@@ -149 +152 @@
         final URL pluginJarUrl = Utils.fileToURL(pluginJar);
         return AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
+              @Override
               public ClassLoader run() {
                   return new URLClassLoader(new URL[] {pluginJarUrl}, Main.class.getClassLoader());

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());