From f335a93cf49c2f7e1af9544c497800d02c8879e6 Mon Sep 17 00:00:00 2001 From: hneemann Date: Sat, 9 Apr 2016 14:07:55 +0200 Subject: [PATCH] added some documentation --- .../de/neemann/digital/core/SpeedTest.java | 4 +- .../de/neemann/digital/core/basic/FanIn.java | 2 +- .../digital/core/element/AttributeKey.java | 26 ++++++ .../core/element/AttributeListener.java | 7 ++ .../neemann/digital/core/element/Element.java | 2 +- .../core/element/ElementAttributes.java | 83 ++++++++++++++++++- .../digital/core/element/ElementFactory.java | 8 ++ .../core/element/ElementTypeDescription.java | 25 +++++- .../digital/core/element/Rotation.java | 24 +++++- .../digital/core/element/ShapeFactory.java | 10 --- .../digital/core/element/package-info.java | 6 ++ .../de/neemann/digital/core/io/Const.java | 2 +- .../java/de/neemann/digital/core/io/In.java | 2 +- .../de/neemann/digital/core/wiring/Clock.java | 2 +- .../de/neemann/digital/core/wiring/Reset.java | 2 +- .../digital/draw/elements/VisualElement.java | 2 +- .../digital/draw/shapes/ShapeFactory.java | 2 +- .../digital/gui/components/EditorFactory.java | 2 +- 18 files changed, 182 insertions(+), 29 deletions(-) delete mode 100644 src/main/java/de/neemann/digital/core/element/ShapeFactory.java create mode 100644 src/main/java/de/neemann/digital/core/element/package-info.java diff --git a/src/main/java/de/neemann/digital/core/SpeedTest.java b/src/main/java/de/neemann/digital/core/SpeedTest.java index ec627608c..135460a00 100644 --- a/src/main/java/de/neemann/digital/core/SpeedTest.java +++ b/src/main/java/de/neemann/digital/core/SpeedTest.java @@ -19,9 +19,9 @@ public class SpeedTest { public double calculate() throws NodeException { ArrayList clocks = model.getClocks(); if (clocks.isEmpty()) - throw new NodeException(Lang.get("err_noClockFound"), null); + throw new NodeException(Lang.get("err_noClockFound")); else if (clocks.size() > 1) - throw new NodeException(Lang.get("err_moreThenOneClocksFound"), null); + throw new NodeException(Lang.get("err_moreThenOneClocksFound")); Clock clock = clocks.get(0); diff --git a/src/main/java/de/neemann/digital/core/basic/FanIn.java b/src/main/java/de/neemann/digital/core/basic/FanIn.java index b048b345b..75c264943 100644 --- a/src/main/java/de/neemann/digital/core/basic/FanIn.java +++ b/src/main/java/de/neemann/digital/core/basic/FanIn.java @@ -38,7 +38,7 @@ public abstract class FanIn extends Node implements Element { } public static class FanInDescription extends ElementTypeDescription { - public FanInDescription(Class clazz) { + public FanInDescription(Class clazz) { super(clazz); addAttributes(); } diff --git a/src/main/java/de/neemann/digital/core/element/AttributeKey.java b/src/main/java/de/neemann/digital/core/element/AttributeKey.java index ff09fe970..11710e0eb 100644 --- a/src/main/java/de/neemann/digital/core/element/AttributeKey.java +++ b/src/main/java/de/neemann/digital/core/element/AttributeKey.java @@ -4,6 +4,9 @@ import de.neemann.digital.core.memory.DataField; import de.neemann.digital.lang.Lang; /** + * A key for a single attribute + * + * @param the type of the value * @author hneemann */ public class AttributeKey { @@ -47,18 +50,34 @@ public class AttributeKey { this.def = def; } + /** + * Returns the attributes key + * + * @return the key + */ public String getKey() { return key; } + /** + * Returns the attributes display name + * + * @return thr name + */ public String getName() { return name; } + /** + * @return the default value of this key + */ public VALUE getDefault() { return def; } + /** + * @return The values class + */ public Class getValueClass() { return def.getClass(); } @@ -68,6 +87,10 @@ public class AttributeKey { return name; } + /** + * A integer attribute. + * Stores additional combo box values + */ public static final class AttributeKeyInteger extends AttributeKey { private Integer[] values; @@ -80,6 +103,9 @@ public class AttributeKey { return this; } + /** + * @return the values to show in the combo box + */ public Integer[] getComboBoxValues() { return values; } diff --git a/src/main/java/de/neemann/digital/core/element/AttributeListener.java b/src/main/java/de/neemann/digital/core/element/AttributeListener.java index 87fa0d39c..64dd20583 100644 --- a/src/main/java/de/neemann/digital/core/element/AttributeListener.java +++ b/src/main/java/de/neemann/digital/core/element/AttributeListener.java @@ -1,8 +1,15 @@ package de.neemann.digital.core.element; /** + * Interface to implement a AttributeListener + * * @author hneemann */ public interface AttributeListener { + /** + * Is called if an attribute changes + * + * @param key the key which value has changed + */ void attributeChanged(AttributeKey key); } diff --git a/src/main/java/de/neemann/digital/core/element/Element.java b/src/main/java/de/neemann/digital/core/element/Element.java index 2aeb839da..611afb58c 100644 --- a/src/main/java/de/neemann/digital/core/element/Element.java +++ b/src/main/java/de/neemann/digital/core/element/Element.java @@ -16,7 +16,7 @@ public interface Element { * inputs of this element. * * @param inputs the list of ObservableValues to use - * @throws NodeException + * @throws NodeException NodeException */ void setInputs(ObservableValue... inputs) throws NodeException; diff --git a/src/main/java/de/neemann/digital/core/element/ElementAttributes.java b/src/main/java/de/neemann/digital/core/element/ElementAttributes.java index 9ecc52904..65a425441 100644 --- a/src/main/java/de/neemann/digital/core/element/ElementAttributes.java +++ b/src/main/java/de/neemann/digital/core/element/ElementAttributes.java @@ -7,6 +7,7 @@ import java.util.Map; /** * Describes one concrete Part. + * Its a Key value list, which is used to store the diferent elements attributes. * * @author hneemann */ @@ -14,9 +15,17 @@ public class ElementAttributes { private HashMap attributes; private transient ArrayList listeners; + /** + * Creates a new instance + */ public ElementAttributes() { } + /** + * Creates a deep copy of the given attributes + * + * @param proto the ElementAttributes to copy + */ public ElementAttributes(ElementAttributes proto) { if (proto.attributes != null) { attributes = new HashMap<>(); @@ -26,6 +35,15 @@ public class ElementAttributes { } } + /** + * Gets a value from the map. + * If the value is not present the default value is returned + * + * @param key the key + * @param the type of the value + * @return the value + */ + @SuppressWarnings("unchecked") public VALUE get(AttributeKey key) { if (attributes == null) return key.getDefault(); @@ -37,6 +55,13 @@ public class ElementAttributes { } } + /** + * Checks if a value is present. + * + * @param key the key + * @param the type of the value + * @return true if value is present + */ public boolean contains(AttributeKey key) { if (attributes == null) return false; @@ -44,6 +69,14 @@ public class ElementAttributes { return attributes.containsKey(key.getKey()); } + /** + * Sets a value + * + * @param key the key + * @param value the value + * @param the type of the value + * @return this to chain calls + */ public ElementAttributes set(AttributeKey key, VALUE value) { if (value != get(key)) { if (value.equals(key.getDefault())) { @@ -68,6 +101,11 @@ public class ElementAttributes { l.attributeChanged(key); } + /** + * Adds a listener to this class + * + * @param listener the listener + */ public void addListener(AttributeListener listener) { if (listeners == null) listeners = new ArrayList<>(); @@ -75,19 +113,43 @@ public class ElementAttributes { listeners.add(listener); } + /** + * removes a listener to this class + * + * @param listener the listener + */ public void removeListener(AttributeListener listener) { if (listeners != null) listeners.remove(listener); } + /** + * Returns the bits count stored in this attributes. + * Its a short hand for get(AttributeKey.Bits) + * + * @return the number of bits + */ public int getBits() { return get(AttributeKey.Bits); } + /** + * Returns the label stored in this attributes. + * Its a short hand for get(AttributeKey.Label) + * + * @return the label + */ public String getLabel() { return get(AttributeKey.Label); } + /** + * Sets the bit count to this map. + * Shorthand for set(AttributeKey.Bits, bits); + * + * @param bits the number of bits + * @return this tp chain calls + */ public ElementAttributes setBits(int bits) { set(AttributeKey.Bits, bits); return this; @@ -95,17 +157,26 @@ public class ElementAttributes { @Override public String toString() { - return "ElementAttributes{" + - "attributes=" + attributes + - '}'; + return "ElementAttributes{" + + "attributes=" + attributes + + '}'; } + /** + * @return true if map is empty + */ public boolean isEmpty() { if (attributes == null) return true; return attributes.isEmpty(); } + /** + * Gets a file stored directly in the map + * + * @param fileKey the file key + * @return the file + */ public File getFile(String fileKey) { if (attributes != null) { Object f = attributes.get(fileKey); @@ -115,6 +186,12 @@ public class ElementAttributes { return null; } + /** + * Stores a file directly in the map + * + * @param fileKey the key + * @param file the file + */ public void setFile(String fileKey, File file) { if (attributes == null) attributes = new HashMap<>(); diff --git a/src/main/java/de/neemann/digital/core/element/ElementFactory.java b/src/main/java/de/neemann/digital/core/element/ElementFactory.java index 6b88bbf55..a8d99f1e8 100644 --- a/src/main/java/de/neemann/digital/core/element/ElementFactory.java +++ b/src/main/java/de/neemann/digital/core/element/ElementFactory.java @@ -1,8 +1,16 @@ package de.neemann.digital.core.element; /** + * Interface is used to implement a factory for elements + * * @author hneemann */ public interface ElementFactory { + /** + * creates a new element matching the given attributes + * + * @param attributes the attributes describing the element + * @return the created element + */ Element create(ElementAttributes attributes); } diff --git a/src/main/java/de/neemann/digital/core/element/ElementTypeDescription.java b/src/main/java/de/neemann/digital/core/element/ElementTypeDescription.java index fbca0b397..114437cd2 100644 --- a/src/main/java/de/neemann/digital/core/element/ElementTypeDescription.java +++ b/src/main/java/de/neemann/digital/core/element/ElementTypeDescription.java @@ -19,11 +19,24 @@ public class ElementTypeDescription { private final String[] inputNames; private final ArrayList attributeList; - public ElementTypeDescription(Class clazz, String... inputNames) { + /** + * Creates a new ElementTypeDescription + * + * @param clazz the elements class + * @param inputNames names of the input signals + */ + public ElementTypeDescription(Class clazz, String... inputNames) { this(clazz.getSimpleName(), clazz, inputNames); } - public ElementTypeDescription(String name, Class clazz, String... inputNames) { + /** + * Creates a new ElementTypeDescription + * + * @param name name of this element + * @param clazz the elements class + * @param inputNames names of the input signals + */ + public ElementTypeDescription(String name, Class clazz, String... inputNames) { this(name, new ElementFactory() { @Override public Element create(ElementAttributes attributes) { @@ -37,6 +50,13 @@ public class ElementTypeDescription { }, inputNames); } + /** + * Creates a new ElementTypeDescription + * + * @param name name of this element + * @param elementFactory factory used to create the element + * @param inputNames names of the input signals + */ public ElementTypeDescription(String name, ElementFactory elementFactory, String... inputNames) { this.name = name; this.shortName = name; @@ -108,6 +128,7 @@ public class ElementTypeDescription { * * @param elementAttributes the elements attributes * @return the list of input names + * @throws NodeException NodeException */ public String[] getInputNames(ElementAttributes elementAttributes) throws NodeException { return inputNames; diff --git a/src/main/java/de/neemann/digital/core/element/Rotation.java b/src/main/java/de/neemann/digital/core/element/Rotation.java index e31e55a1b..94efdabc3 100644 --- a/src/main/java/de/neemann/digital/core/element/Rotation.java +++ b/src/main/java/de/neemann/digital/core/element/Rotation.java @@ -1,13 +1,31 @@ package de.neemann.digital.core.element; /** + * Warapper for the elements rotation + * * @author hneemann */ public class Rotation { - public int rotation; + /** + * The rotation value. + * is in between 0 and 3 + */ + private final int rotation; - public Rotation(int rot) { - rotation = rot; + /** + * Creates a new instance + * + * @param rotation the rotation + */ + public Rotation(int rotation) { + this.rotation = rotation; + } + + /** + * @return the rotation value + */ + public int getRotation() { + return rotation; } @Override diff --git a/src/main/java/de/neemann/digital/core/element/ShapeFactory.java b/src/main/java/de/neemann/digital/core/element/ShapeFactory.java deleted file mode 100644 index 2557b163d..000000000 --- a/src/main/java/de/neemann/digital/core/element/ShapeFactory.java +++ /dev/null @@ -1,10 +0,0 @@ -package de.neemann.digital.core.element; - -import de.neemann.digital.draw.shapes.Shape; - -/** - * @author hneemann - */ -public interface ShapeFactory { - Shape create(ElementAttributes elementAttributes); -} diff --git a/src/main/java/de/neemann/digital/core/element/package-info.java b/src/main/java/de/neemann/digital/core/element/package-info.java new file mode 100644 index 000000000..50b916c90 --- /dev/null +++ b/src/main/java/de/neemann/digital/core/element/package-info.java @@ -0,0 +1,6 @@ +/** + * This package contains the classes used to describe and create the elements. + * + * @author hneemann + */ +package de.neemann.digital.core.element; diff --git a/src/main/java/de/neemann/digital/core/io/Const.java b/src/main/java/de/neemann/digital/core/io/Const.java index 99c34c6b4..c653f15ef 100644 --- a/src/main/java/de/neemann/digital/core/io/Const.java +++ b/src/main/java/de/neemann/digital/core/io/Const.java @@ -28,7 +28,7 @@ public class Const implements Element { @Override public void setInputs(ObservableValue... inputs) throws NodeException { - throw new NodeException(Lang.get("err_noInputsAvailable"), null); + throw new NodeException(Lang.get("err_noInputsAvailable")); } @Override diff --git a/src/main/java/de/neemann/digital/core/io/In.java b/src/main/java/de/neemann/digital/core/io/In.java index 30cfe70c4..ec1234f96 100644 --- a/src/main/java/de/neemann/digital/core/io/In.java +++ b/src/main/java/de/neemann/digital/core/io/In.java @@ -31,7 +31,7 @@ public class In implements Element { @Override public void setInputs(ObservableValue... inputs) throws NodeException { - throw new NodeException(Lang.get("err_noInputsAvailable"), null); + throw new NodeException(Lang.get("err_noInputsAvailable")); } @Override diff --git a/src/main/java/de/neemann/digital/core/wiring/Clock.java b/src/main/java/de/neemann/digital/core/wiring/Clock.java index a71de4a6a..8c9c1e5c9 100644 --- a/src/main/java/de/neemann/digital/core/wiring/Clock.java +++ b/src/main/java/de/neemann/digital/core/wiring/Clock.java @@ -33,7 +33,7 @@ public class Clock implements Element { @Override public void setInputs(ObservableValue... inputs) throws NodeException { - throw new NodeException(Lang.get("err_noInputsAvailable"), null); + throw new NodeException(Lang.get("err_noInputsAvailable")); } @Override diff --git a/src/main/java/de/neemann/digital/core/wiring/Reset.java b/src/main/java/de/neemann/digital/core/wiring/Reset.java index d6e9ec6e0..8fd4c890d 100644 --- a/src/main/java/de/neemann/digital/core/wiring/Reset.java +++ b/src/main/java/de/neemann/digital/core/wiring/Reset.java @@ -26,7 +26,7 @@ public class Reset implements Element { @Override public void setInputs(ObservableValue... inputs) throws NodeException { - throw new NodeException(Lang.get("err_noInputsAvailable"), null); + throw new NodeException(Lang.get("err_noInputsAvailable")); } @Override diff --git a/src/main/java/de/neemann/digital/draw/elements/VisualElement.java b/src/main/java/de/neemann/digital/draw/elements/VisualElement.java index d47b74299..89f4e6a81 100644 --- a/src/main/java/de/neemann/digital/draw/elements/VisualElement.java +++ b/src/main/java/de/neemann/digital/draw/elements/VisualElement.java @@ -195,7 +195,7 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { public void attributeChanged(AttributeKey key) { shape = null; minMax = null; - rotate = elementAttributes.get(AttributeKey.Rotate).rotation; + rotate = elementAttributes.get(AttributeKey.Rotate).getRotation(); } @Override diff --git a/src/main/java/de/neemann/digital/draw/shapes/ShapeFactory.java b/src/main/java/de/neemann/digital/draw/shapes/ShapeFactory.java index 7efddc3ce..474ab19fd 100644 --- a/src/main/java/de/neemann/digital/draw/shapes/ShapeFactory.java +++ b/src/main/java/de/neemann/digital/draw/shapes/ShapeFactory.java @@ -77,7 +77,7 @@ public final class ShapeFactory { try { if (cr == null) { if (library == null) - throw new NodeException(Lang.get("err_noShapeFoundFor_N", partName), null); + throw new NodeException(Lang.get("err_noShapeFoundFor_N", partName)); else { ElementTypeDescription pt = library.getElementType(partName); if (pt instanceof LibrarySelector.ElementTypeDescriptionCustom) { diff --git a/src/main/java/de/neemann/digital/gui/components/EditorFactory.java b/src/main/java/de/neemann/digital/gui/components/EditorFactory.java index d5a4de639..b2c411e7d 100644 --- a/src/main/java/de/neemann/digital/gui/components/EditorFactory.java +++ b/src/main/java/de/neemann/digital/gui/components/EditorFactory.java @@ -241,7 +241,7 @@ public final class EditorFactory { @Override public Component getComponent(ElementAttributes elementAttributes) { comb = new JComboBox<>(LIST); - comb.setSelectedIndex(rotation.rotation); + comb.setSelectedIndex(rotation.getRotation()); return comb; }