From 17da90c32c0ae2f9c8da432a886bd0ef77be5515 Mon Sep 17 00:00:00 2001 From: Mikael Capelle Date: Mon, 12 Mar 2018 17:13:02 +0100 Subject: [PATCH] Update javadoc. --- src/main/org/insa/graph/GraphStatistics.java | 2 +- .../org/insa/graphics/AlgorithmPanel.java | 38 +++++++++++++-- .../org/insa/graphics/NodesInputPanel.java | 19 ++++++-- .../org/insa/graphics/StreamCapturer.java | 9 +++- .../drawing/components/BasicDrawing.java | 4 -- .../org/insa/graphics/utils/FileUtils.java | 46 +++++++++++++++++-- 6 files changed, 98 insertions(+), 20 deletions(-) diff --git a/src/main/org/insa/graph/GraphStatistics.java b/src/main/org/insa/graph/GraphStatistics.java index d4f4b71..91c6e35 100644 --- a/src/main/org/insa/graph/GraphStatistics.java +++ b/src/main/org/insa/graph/GraphStatistics.java @@ -100,7 +100,7 @@ public class GraphStatistics { * * @param boundingBox Bounding-box for the graph. * @param nbRoadOneWay Number of one-way roads in the graph. - * @param nbRoadTwoTayws Number of two-ways roads in the graph. + * @param nbRoadTwoWays Number of two-ways roads in the graph. * @param maximumSpeed Maximum speed of any road of the graph. You can use * {@link #NO_MAXIMUM_SPEED} to indicate that the graph has no maximum * speed limit. diff --git a/src/main/org/insa/graphics/AlgorithmPanel.java b/src/main/org/insa/graphics/AlgorithmPanel.java index 514c3b8..04acac5 100644 --- a/src/main/org/insa/graphics/AlgorithmPanel.java +++ b/src/main/org/insa/graphics/AlgorithmPanel.java @@ -139,6 +139,19 @@ public class AlgorithmPanel extends JPanel implements DrawingChangeListener { List startActionListeners = new ArrayList<>(); /** + * Create a new AlgorithmPanel with the given parameters. + * + * @param parent Parent component for this panel. Only use for centering + * dialogs. + * @param baseAlgorithm Base algorithm for this algorithm panel. + * @param title Title of the panel. + * @param nodeNames Names of the input nodes. + * @param enableModeSelection true to enable {@link Mode} + * selection. + * @param enableArcFilterSelection true to enable {@link ArcFilter} + * selection. + * + * @see ArcFilterFactory */ public AlgorithmPanel(Component parent, Class> baseAlgorithm, String title, String[] nodeNames, boolean enableModeSelection, @@ -312,7 +325,7 @@ public class AlgorithmPanel extends JPanel implements DrawingChangeListener { * * @param title Title for the label. * - * @return + * @return A new JLabel containing the given title with proper font. */ protected JLabel createTitleLabel(String title) { JLabel titleLabel = new JLabel(title); @@ -328,7 +341,12 @@ public class AlgorithmPanel extends JPanel implements DrawingChangeListener { /** * Create the combo box for the algorithm selection. * - * @return + * @param baseAlgorithm Base algorithm for which the select box should be + * created. + * + * @return A new JComboBox containing algorithms for the given base algorithm. + * + * @see AlgorithmFactory */ protected JComboBox createAlgoritmSelectComboBox( Class> baseAlgorithm) { @@ -343,8 +361,9 @@ public class AlgorithmPanel extends JPanel implements DrawingChangeListener { /** * Create a node input panel with the given node input names. * - * @param nodeNames - * @return + * @param nodeNames Field names for the inputs to create. + * + * @return A new NodesInputPanel containing inputs for the given names. */ protected NodesInputPanel createNodesInputPanel(String[] nodeNames) { final Color[] nodeColors = { new Color(57, 172, 115), new Color(255, 77, 77), @@ -358,6 +377,15 @@ public class AlgorithmPanel extends JPanel implements DrawingChangeListener { return panel; } + /** + * Check if the given list of nodes does not contain any null + * value. + * + * @param nodes List of {@link Node} to check. + * + * @return true if the list does not contain any null + * value, false otherwise. + */ protected boolean allNotNull(List nodes) { boolean allNotNull = true; for (Node node: nodes) { @@ -382,7 +410,7 @@ public class AlgorithmPanel extends JPanel implements DrawingChangeListener { /** * Add a new start action listener to this class. * - * @param listener + * @param listener Listener to add. */ public void addStartActionListener(ActionListener listener) { this.startActionListeners.add(listener); diff --git a/src/main/org/insa/graphics/NodesInputPanel.java b/src/main/org/insa/graphics/NodesInputPanel.java index e0eed9e..e9d6e52 100644 --- a/src/main/org/insa/graphics/NodesInputPanel.java +++ b/src/main/org/insa/graphics/NodesInputPanel.java @@ -59,7 +59,7 @@ public class NodesInputPanel extends JPanel * @param point * * @return the closest node to the given point, or null if no node is "close - * enough". + * enough". */ public Node findClosestNode(Point point) { Node minNode = null; @@ -124,14 +124,23 @@ public class NodesInputPanel extends JPanel private NodeFinder nodeFinder; /** - * @param drawing Original drawing used (see {@link:newDrawingLoaded}). - * @param graph Original graph used (see {@link:newGraphLoaded}); + * Create a new NodesInputPanel. + * */ public NodesInputPanel() { super(new GridBagLayout()); initInputToFill(); } + /** + * Add an InputChanged listener to this panel. This listener will be notified by + * a {@link InputChangedEvent} each time an input in this panel change (click, + * clear, manual input). + * + * @param listener Listener to add. + * + * @see InputChangedEvent + */ public void addInputChangedListener(ActionListener listener) { inputChangeListeners.add(listener); } @@ -293,7 +302,7 @@ public class NodesInputPanel extends JPanel /** * @return The node for the given text field, or null if the content of the text - * field is invalid. + * field is invalid. */ protected Node getNodeForInput(JTextField textfield) { try { @@ -307,7 +316,7 @@ public class NodesInputPanel extends JPanel /** * @return List of nodes associated with the input. Some nodes may be null if - * their associated input is invalid. + * their associated input is invalid. */ public List getNodeForInputs() { List nodes = new ArrayList<>(nodeInputs.size()); diff --git a/src/main/org/insa/graphics/StreamCapturer.java b/src/main/org/insa/graphics/StreamCapturer.java index 9dd9f26..d7f47d2 100644 --- a/src/main/org/insa/graphics/StreamCapturer.java +++ b/src/main/org/insa/graphics/StreamCapturer.java @@ -12,8 +12,8 @@ public class StreamCapturer extends OutputStream { private JTextArea output; /** - * @param prefix - * @param output + * @param output Output JTextArea to which this stream should print. + * @param prefix Prefix to add to each line of this output. */ public StreamCapturer(JTextArea output, String prefix) { this.prefix = prefix; @@ -21,6 +21,11 @@ public class StreamCapturer extends OutputStream { this.output = output; } + /** + * Create a new StreamCapturer without prefix. + * + * @param output Output JTextArea to which this stream should print. + */ public StreamCapturer(JTextArea output) { this(output, null); } diff --git a/src/main/org/insa/graphics/drawing/components/BasicDrawing.java b/src/main/org/insa/graphics/drawing/components/BasicDrawing.java index b572112..c75b1db 100644 --- a/src/main/org/insa/graphics/drawing/components/BasicDrawing.java +++ b/src/main/org/insa/graphics/drawing/components/BasicDrawing.java @@ -398,7 +398,6 @@ public class BasicDrawing extends JPanel implements Drawing { /* * (non-Javadoc) - * * @see org.insa.graphics.drawing.Drawing#clear() */ @Override @@ -414,7 +413,6 @@ public class BasicDrawing extends JPanel implements Drawing { /* * (non-Javadoc) - * * @see org.insa.graphics.drawing.Drawing#clearOverlays() */ @Override @@ -458,7 +456,6 @@ public class BasicDrawing extends JPanel implements Drawing { /* * (non-Javadoc) - * * @see * org.insa.graphics.drawing.Drawing#addDrawingClickListener(org.insa.graphics. * drawing.DrawingClickListener) @@ -470,7 +467,6 @@ public class BasicDrawing extends JPanel implements Drawing { /* * (non-Javadoc) - * * @see org.insa.graphics.drawing.Drawing#removeDrawingClickListener(org.insa. * graphics.drawing.DrawingClickListener) */ diff --git a/src/main/org/insa/graphics/utils/FileUtils.java b/src/main/org/insa/graphics/utils/FileUtils.java index b8a7210..3584f6e 100644 --- a/src/main/org/insa/graphics/utils/FileUtils.java +++ b/src/main/org/insa/graphics/utils/FileUtils.java @@ -16,8 +16,26 @@ public class FileUtils { // Preferences private static Preferences preferences = Preferences.userRoot().node(FileUtils.class.getName()); + /** + * Type of folder with associated preferred folder and path filters. + * + */ public enum FolderType { - Map, PathInput, PathOutput + + /** + * Folder type for graph files input (*.mapgr). + */ + Map, + + /** + * Folder type for path inputs (*.path). + */ + PathInput, + + /** + * Folder type for path outputs (*.path). + */ + PathOutput } private static class PreferencesEntry { @@ -55,7 +73,11 @@ public class FileUtils { } /** + * @param folderType Type of folder to retrieve. + * * @return A File instance pointing to the preferred folder for the given type. + * + * @see FolderType */ public static File getPreferredFolder(FolderType folderType) { PreferencesEntry entry = folderToEntry.get(folderType); @@ -66,12 +88,18 @@ public class FileUtils { return folder; } + /** + * @param folderType Type of folder to update. + * @param newPreferredFolder New preferred folder. + */ public static void updatePreferredFolder(FolderType folderType, File newPreferredFolder) { PreferencesEntry entry = folderToEntry.get(folderType); preferences.put(entry.key, newPreferredFolder.getAbsolutePath()); } /** + * @param folderType Type of folder for which the filter should be retrieved. + * * @return A FileFilter corresponding to input graph files. */ public static FileFilter getFileFilter(FolderType folderType) { @@ -79,8 +107,12 @@ public class FileUtils { } /** - * @param folderType - * @return + * @param folderType Type of folder for which a file chooser should be created. + * @param defaultFileName Default file name to show, or null to not show any + * file. + * + * @return A new JFileChooser pointing to the preferred folder for the given + * folderType, with the given default file selected (if given). */ public static JFileChooser createFileChooser(FolderType folderType, String defaultFileName) { JFileChooser chooser = new JFileChooser(); @@ -104,6 +136,14 @@ public class FileUtils { return chooser; } + /** + * @param folderType Type of folder for which a file chooser should be created. + * + * @return A new JFileChooser pointing to the preferred folder for the given + * folderType. + * + * @see #createFileChooser(FolderType, String) + */ public static JFileChooser createFileChooser(FolderType folderType) { return createFileChooser(folderType, null); }