Index: trunk/src/org/openstreetmap/josm/actions/DownloadAlongAction.java =================================================================== --- trunk/src/org/openstreetmap/josm/actions/DownloadAlongAction.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/actions/DownloadAlongAction.java (revision 8926) @@ -10,4 +10,6 @@ import java.util.Collection; import java.util.List; +import java.util.concurrent.CancellationException; +import java.util.concurrent.ExecutionException; import java.util.concurrent.Future; @@ -91,4 +93,11 @@ * This functions calculates the rectangles, asks the user to continue and downloads * the areas if applicable. + * + * @param a download area hull + * @param maxArea maximum area size for a single download + * @param osmDownload Set to true if OSM data should be downloaded + * @param gpxDownload Set to true if GPX data should be downloaded + * @param title the title string for the confirmation dialog + * @param progressMonitor the progress monitor */ protected static void confirmAndDownloadAreas(Area a, double maxArea, boolean osmDownload, boolean gpxDownload, String title, Index: trunk/src/org/openstreetmap/josm/actions/JoinAreasAction.java =================================================================== --- trunk/src/org/openstreetmap/josm/actions/JoinAreasAction.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/actions/JoinAreasAction.java (revision 8926) @@ -930,6 +930,8 @@ /** - * This is a method splits way into smaller parts, using the prepared nodes list as split points. + * This is a method that splits way into smaller parts, using the prepared nodes list as split points. * Uses {@link SplitWayAction#splitWay} for the heavy lifting. + * @param way way to split + * @param nodes split points * @return list of split ways (or original ways if no splitting is done). */ @@ -1142,4 +1144,5 @@ * This method checks if polygons have several touching parts and splits them in several polygons. * @param polygons the polygons to process. + * @return the resulting list of polygons */ public static List fixTouchingPolygons(List polygons) { Index: trunk/src/org/openstreetmap/josm/actions/OrthogonalizeAction.java =================================================================== --- trunk/src/org/openstreetmap/josm/actions/OrthogonalizeAction.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/actions/OrthogonalizeAction.java (revision 8926) @@ -245,5 +245,5 @@ * - The same for vertical segments. * 5. Rotate back. - * + * @throws InvalidUserInputException if selected ways have an angle different from 90 or 180 degrees **/ private static Collection orthogonalize(List wayDataList, List headingNodes) throws InvalidUserInputException { @@ -536,4 +536,5 @@ * Recognize angle to be approximately 0, 90, 180 or 270 degrees. * returns an integral value, corresponding to a counter clockwise turn: + * @throws RejectedAngleException in case of invalid angle */ private static int angleToDirectionChange(double a, double deltaMax) throws RejectedAngleException { Index: trunk/src/org/openstreetmap/josm/data/Preferences.java =================================================================== --- trunk/src/org/openstreetmap/josm/data/Preferences.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/data/Preferences.java (revision 8926) @@ -837,4 +837,5 @@ /** * Called after every put. In case of a problem, do nothing but output the error in log. + * @throws IOException if any I/O error occurs */ public void save() throws IOException { Index: trunk/src/org/openstreetmap/josm/gui/ConditionalOptionPaneUtil.java =================================================================== --- trunk/src/org/openstreetmap/josm/gui/ConditionalOptionPaneUtil.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/gui/ConditionalOptionPaneUtil.java (revision 8926) @@ -113,4 +113,5 @@ * * @return the option selected by user. {@link JOptionPane#CLOSED_OPTION} if the dialog was closed. + * @throws HeadlessException if GraphicsEnvironment.isHeadless returns true */ public static int showOptionDialog(String preferenceKey, Component parent, Object message, String title, int optionType, @@ -153,4 +154,5 @@ * * @return true, if the selected option is equal to trueOption, otherwise false. + * @throws HeadlessException if GraphicsEnvironment.isHeadless returns true * * @see JOptionPane#INFORMATION_MESSAGE Index: trunk/src/org/openstreetmap/josm/gui/tagging/presets/TaggingPreset.java =================================================================== --- trunk/src/org/openstreetmap/josm/gui/tagging/presets/TaggingPreset.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/gui/tagging/presets/TaggingPreset.java (revision 8926) @@ -198,4 +198,5 @@ /** * Called from the XML parser to set the types this preset affects. + * @throws SAXException if any SAX error occurs */ public void setType(String types) throws SAXException { Index: trunk/src/org/openstreetmap/josm/io/BoundingBoxDownloader.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/BoundingBoxDownloader.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/BoundingBoxDownloader.java (revision 8926) @@ -128,4 +128,5 @@ /** * Parse the given input source and return the dataset. + * @throws IllegalDataException if an error was found while parsing the OSM data * * @see OsmReader#parseDataSet(InputStream, ProgressMonitor) Index: trunk/src/org/openstreetmap/josm/io/CacheCustomContent.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/CacheCustomContent.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/CacheCustomContent.java (revision 8926) @@ -60,4 +60,5 @@ * executed in the current thread. * @return the data to cache + * @throws T a {@link Throwable} */ protected abstract byte[] updateData() throws T; @@ -175,4 +176,5 @@ /** * Tries to load the data using the given ident from disk. If this fails, data will be updated, unless run in offline mode + * @throws T a {@link Throwable} */ private void loadFromDisk() throws T { Index: trunk/src/org/openstreetmap/josm/io/OsmApi.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/OsmApi.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/OsmApi.java (revision 8926) @@ -877,5 +877,10 @@ } - /** Method for parsing API responses for operations on individual notes */ + /** + * Method for parsing API responses for operations on individual notes + * @param xml the API response as XML data + * @return the resulting Note + * @throws OsmTransferException if the API response cannot be parsed + */ private Note parseSingleNote(String xml) throws OsmTransferException { try { Index: trunk/src/org/openstreetmap/josm/io/OsmImporter.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/OsmImporter.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/OsmImporter.java (revision 8926) @@ -84,4 +84,5 @@ * @param associatedFile filename of data (layer name will be generated from name of file) * @param pm handler for progress monitoring and canceling + * @throws IllegalDataException if an error was found while parsing the OSM data */ protected void importData(InputStream in, final File associatedFile, ProgressMonitor pm) throws IllegalDataException { @@ -112,4 +113,5 @@ * @param layerName name of generated layer * @param progressMonitor handler for progress monitoring and canceling + * @throws IllegalDataException if an error was found while parsing the OSM data */ public OsmImporterData loadLayer(InputStream in, final File associatedFile, final String layerName, ProgressMonitor progressMonitor) Index: trunk/src/org/openstreetmap/josm/io/OsmReader.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/OsmReader.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/OsmReader.java (revision 8926) @@ -398,4 +398,5 @@ * This is basically the same code as parseUnknown(), except for the warnings, which * are displayed for inner elements and not at top level. + * @throws XMLStreamException if there is an error processing the underlying XML source */ private void jumpToEnd(boolean printWarning) throws XMLStreamException { @@ -430,4 +431,5 @@ /** * Read out the common attributes and put them into current OsmPrimitive. + * @throws XMLStreamException if there is an error processing the underlying XML source */ private void readCommon(PrimitiveData current) throws XMLStreamException { Index: trunk/src/org/openstreetmap/josm/io/UTFInputStreamReader.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/UTFInputStreamReader.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/UTFInputStreamReader.java (revision 8926) @@ -16,4 +16,5 @@ * Creates a new {@link InputStreamReader} from the {@link InputStream} with UTF-8 as default encoding. * @return A reader with the correct encoding. Starts to read after the BOM. + * @throws IOException if any I/O error occurs * @see #create(java.io.InputStream, String) */ @@ -26,4 +27,5 @@ * @param defaultEncoding Used, when no BOM was recognized. Can be null. * @return A reader with the correct encoding. Starts to read after the BOM. + * @throws IOException if any I/O error occurs */ public static UTFInputStreamReader create(InputStream input, String defaultEncoding) throws IOException { Index: trunk/src/org/openstreetmap/josm/io/remotecontrol/RemoteControlHttpsServer.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/remotecontrol/RemoteControlHttpsServer.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/remotecontrol/RemoteControlHttpsServer.java (revision 8926) @@ -134,8 +134,10 @@ * @param algorithm the signing algorithm, eg "SHA256withRSA" * @param san SubjectAlternativeName extension (optional) + * @return the self-signed X.509 Certificate + * @throws GeneralSecurityException if any security error occurs + * @throws IOException if any I/O error occurs */ private static X509Certificate generateCertificate(String dn, KeyPair pair, int days, String algorithm, String san) throws GeneralSecurityException, IOException { - PrivateKey privkey = pair.getPrivate(); X509CertInfo info = new X509CertInfo(); Date from = new Date(); @@ -193,4 +195,5 @@ // Sign the cert to identify the algorithm that's used. + PrivateKey privkey = pair.getPrivate(); X509CertImpl cert = new X509CertImpl(info); cert.sign(privkey, algorithm); Index: trunk/src/org/openstreetmap/josm/io/session/SessionLayerExporter.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/session/SessionLayerExporter.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/session/SessionLayerExporter.java (revision 8926) @@ -6,8 +6,7 @@ import java.util.Collection; -import org.w3c.dom.Element; - import org.openstreetmap.josm.gui.layer.Layer; import org.openstreetmap.josm.io.session.SessionWriter.ExportSupport; +import org.w3c.dom.Element; public interface SessionLayerExporter { @@ -15,4 +14,5 @@ /** * Return the Layers, this Layer depends on. + * @return the layer dependencies */ Collection getDependencies(); @@ -20,22 +20,22 @@ /** * The GUI for exporting this layer. + * @return the export panel */ Component getExportPanel(); /** - * Return true, if the layer should be included in the - * list of exported layers. + * Return true, if the layer should be included in the list of exported layers. * * The user can veto this in the export panel. + * @return {@code true} if the layer should be included in the list of exported layers, {@code false} otherwise. */ boolean shallExport(); /** - * Return true, if some data needs to be included in - * the zip archive. This decision depends on the user + * Return true, if some data needs to be included in the zip archive. This decision depends on the user * selection in the export panel. * - * If any layer requires zip, the user can only save as - * .joz. Otherwise both .jos and .joz are possible. + * If any layer requires zip, the user can only save as .joz. Otherwise both .jos and .joz are possible. + * @return {@code true} if some data needs to be included in the zip archive, {@code false} otherwise. */ boolean requiresZip(); @@ -44,7 +44,8 @@ * Save meta data to the .jos file. Return a layer XML element. * Use support to save files in the zip archive as needed. + * @param support support class providing export utilities + * @return the resulting XML element + * @throws IOException if any I/O error occurs */ Element export(ExportSupport support) throws IOException; - } - Index: trunk/src/org/openstreetmap/josm/io/session/SessionLayerImporter.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/session/SessionLayerImporter.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/session/SessionLayerImporter.java (revision 8926) @@ -4,14 +4,20 @@ import java.io.IOException; -import org.w3c.dom.Element; - import org.openstreetmap.josm.gui.layer.Layer; import org.openstreetmap.josm.gui.progress.ProgressMonitor; import org.openstreetmap.josm.io.IllegalDataException; import org.openstreetmap.josm.io.session.SessionReader.ImportSupport; +import org.w3c.dom.Element; public interface SessionLayerImporter { + /** * Load the layer from xml meta-data. + * @param elem XML element + * @param support support class providing import utilities + * @param progressMonitor progress monitor + * @return the resulting layer + * @throws IOException if any I/O error occurs + * @throws IllegalDataException if invalid data is read */ Layer load(Element elem, ImportSupport support, ProgressMonitor progressMonitor) throws IOException, IllegalDataException; Index: trunk/src/org/openstreetmap/josm/io/session/SessionReader.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/session/SessionReader.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/session/SessionReader.java (revision 8926) @@ -196,4 +196,7 @@ * Returns null if the URI points to a file inside the zip archive. * In this case, inZipPath will be set to the corresponding path. + * @param uriStr the URI as string + * @return the resulting File + * @throws IOException if any I/O error occurs */ public File getFile(String uriStr) throws IOException { Index: trunk/src/org/openstreetmap/josm/io/session/SessionWriter.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/session/SessionWriter.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/io/session/SessionWriter.java (revision 8926) @@ -142,4 +142,5 @@ * @return the OutputStream you can write to. Never close the returned * output stream, but make sure to flush buffers. + * @throws IOException if any I/O error occurs */ public OutputStream getOutputStreamZip(String zipPath) throws IOException { Index: trunk/src/org/openstreetmap/josm/tools/Diff.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/Diff.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/tools/Diff.java (revision 8926) @@ -83,7 +83,5 @@ along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - */ - public class Diff { @@ -94,4 +92,6 @@ be needed again later to print the results of the comparison as an edit script, if desired. + * @param a first array + * @param b second array */ public Diff(Object[] a, Object[] b) { Index: trunk/src/org/openstreetmap/josm/tools/Utils.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/Utils.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/tools/Utils.java (revision 8926) @@ -222,5 +222,8 @@ /** - * return the modulus in the range [0, n) + * Return the modulus in the range [0, n) + * @param a dividend + * @param n divisor + * @return modulo (remainder of the Euclidian division of a by n) */ public static int mod(int a, int n) { Index: trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateParser.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateParser.java (revision 8925) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateParser.java (revision 8926) @@ -1,5 +1,4 @@ // License: GPL. For details, see LICENSE file. package org.openstreetmap.josm.tools.template_engine; - import static org.openstreetmap.josm.tools.I18n.tr; @@ -15,5 +14,7 @@ import org.openstreetmap.josm.tools.template_engine.Tokenizer.TokenType; - +/** + * Template parser. + */ public class TemplateParser { private final Tokenizer tokenizer; @@ -22,4 +23,8 @@ private static final Collection CONDITION_WITH_APOSTROPHES_END_TOKENS = Arrays.asList(TokenType.APOSTROPHE); + /** + * Constructs a new {@code TemplateParser}. + * @param template template to parse + */ public TemplateParser(String template) { this.tokenizer = new Tokenizer(template); @@ -34,4 +39,9 @@ } + /** + * Parse the template. + * @return the resulting template entry + * @throws ParseError if the template cannot be parsed + */ public TemplateEntry parse() throws ParseError { return parseExpression(EXPRESSION_END_TOKENS); @@ -91,5 +101,5 @@ result.getEntries().add(new SearchExpressionCondition( SearchCompiler.compile(searchExpression.getText()), condition)); - } catch (org.openstreetmap.josm.actions.search.SearchCompiler.ParseError e) { + } catch (SearchCompiler.ParseError e) { throw new ParseError(searchExpression.getPosition(), e); } @@ -121,5 +131,5 @@ Match match = SearchCompiler.compile(searchExpression.getText()); result = new ContextSwitchTemplate(match, template, searchExpression.getPosition()); - } catch (org.openstreetmap.josm.actions.search.SearchCompiler.ParseError e) { + } catch (SearchCompiler.ParseError e) { throw new ParseError(searchExpression.getPosition(), e); } @@ -129,4 +139,3 @@ return result; } - }