Skip to content

Commit

Permalink
Fixing Javadoc problems - prt 1
Browse files Browse the repository at this point in the history
  • Loading branch information
@SingingBush
SingingBush committed Oct 11, 2024
1 parent b9d9f7d commit 3c4a5b5
Show file tree
Hide file tree
Showing 7 changed files with 86 additions and 65 deletions.
20 changes: 20 additions & 0 deletions barcode4j/src/main/java/org/krysalis/barcode4j/BarcodeDimension.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,10 @@ public double getHeight() {
return height;
}

/**
* @param orientation The orientation of the barcode (eg: 0, 90, 180 or 270)
* @return height in millimeters (mm) that will take the orientation into account
*/
public double getHeight(int orientation) {
orientation = normalizeOrientation(orientation);
if (orientation % 180 != 0) {
Expand All @@ -96,6 +100,10 @@ public double getHeightPlusQuiet() {
return heightPlusQuiet;
}

/**
* @param orientation The orientation of the barcode (eg: 0, 90, 180 or 270)
* @return height in millimeters (mm) including the Quiet Zone
*/
public double getHeightPlusQuiet(int orientation) {
orientation = normalizeOrientation(orientation);
if (orientation % 180 != 0) {
Expand All @@ -113,6 +121,10 @@ public double getWidth() {
return width;
}

/**
* @param orientation The orientation of the barcode (eg: 0, 90, 180 or 270)
* @return Normalised value for orientation. For example if you pass in -90 method will return positive value equivalent of 270
*/
public static int normalizeOrientation(int orientation) {
switch (orientation) {
case 0:
Expand All @@ -131,6 +143,10 @@ public static int normalizeOrientation(int orientation) {
}
}

/**
* @param orientation The orientation of the barcode (eg: 0, 90, 180 or 270)
* @return width in millimeters (mm) that will take the orientation into account
*/
public double getWidth(int orientation) {
orientation = normalizeOrientation(orientation);
if (orientation % 180 != 0) {
Expand All @@ -148,6 +164,10 @@ public double getWidthPlusQuiet() {
return widthPlusQuiet;
}

/**
* @param orientation The orientation of the barcode (eg: 0, 90, 180 or 270)
* @return width in millimeters (mm) including the Quiet Zone
*/
public double getWidthPlusQuiet(int orientation) {
orientation = normalizeOrientation(orientation);
if (orientation % 180 != 0) {
Expand Down
77 changes: 39 additions & 38 deletions barcode4j/src/main/java/org/krysalis/barcode4j/configuration/Configuration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,44 +58,45 @@
* Assuming the <code>Configuration</code> object is named <code>conf</code>,
* here is how the data could be retrieved:
* </p>
* <p>
* <table border="1">
* <tr align="center"><th>Code</th><th>No namespaces</th><th>With namespaces</th></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getName getName}()</code></td><td colspan="2">my-system</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getAttributeNames getAttributeNames}().length</code>
* </td><td>2</td><td>1</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChildren() getChildren}().length</code>
* </td><td colspan="2">2</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getAttributeAsFloat(String) getAttributeAsFloat}("version")</code>
* </td><td colspan="2">1.3</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChild(String) getChild}("widget").{@link #getAttribute(String) getAttribute}("name")</code>
* </td><td colspan="2">fooWidget</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChild(String) getChild}("widget")
* .{@link #getAttributeAsBoolean(String) getAttributeAsBoolean}("threadsafe")</code></td><td colspan="2">
* <code>true</code></td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChild(String) getChild}("widget").{@link #getLocation getLocation}()</code>
* </td><td colspan="2">file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChild(String) getChild}("desc").{@link #getName getName}()</code>
* </td><td>desc (see {@link #getChild(String)})</td><td>desc</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChild(String) getChild}("doc:desc").{@link #getName getName}()</code>
* </td><td>doc:desc</td><td>doc:desc (see {@link #getChild(String)})</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChild(String) getChild}("desc").{@link #getValue() getValue}()</code>
* </td><td>{@link ConfigurationException}</td><td>This is a highly fictitious config file</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChild(String) getChild}("doc:desc").{@link #getValue() getValue}()</code>
* </td><td>This is a highly fictitious config file</td><td>{@link ConfigurationException}</td></tr>
* <tr align="center"><td align="left">
* <code>conf.{@link #getChild(String) getChild}("desc").{@link #getNamespace getNamespace}()</code>
* </td><td>&nbsp;</td><td>http://myco.com/documentation"</td></tr>
* <tr><th>Code</th><th>No namespaces</th><th>With namespaces</th></tr>
* <tr><td>
* <code>conf.{@link #getName getName}()</code></td><td colspan="2">my-system</td></tr>
* <tr><td>
* <code>conf.{@link #getAttributeNames getAttributeNames}().length</code>
* </td><td>2</td><td>1</td></tr>
* <tr><td>
* <code>conf.{@link #getChildren() getChildren}().length</code>
* </td><td colspan="2">2</td></tr>
* <tr><td>
* <code>conf.{@link #getAttributeAsFloat(String) getAttributeAsFloat}("version")</code>
* </td><td colspan="2">1.3</td></tr>
* <tr><td>
* <code>conf.{@link #getChild(String) getChild}("widget").{@link #getAttribute(String) getAttribute}("name")</code>
* </td><td colspan="2">fooWidget</td></tr>
* <tr><td>
* <code>conf.{@link #getChild(String) getChild}("widget")
* .{@link #getAttributeAsBoolean(String) getAttributeAsBoolean}("threadsafe")</code></td><td colspan="2">
* <code>true</code></td></tr>
* <tr><td>
* <code>conf.{@link #getChild(String) getChild}("widget").{@link #getLocation getLocation}()</code>
* </td><td colspan="2">file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
* <tr><td>
* <code>conf.{@link #getChild(String) getChild}("desc").{@link #getName getName}()</code>
* </td><td>desc (see {@link #getChild(String)})</td><td>desc</td></tr>
* <tr><td>
* <code>conf.{@link #getChild(String) getChild}("doc:desc").{@link #getName getName}()</code>
* </td><td>doc:desc</td><td>doc:desc (see {@link #getChild(String)})</td></tr>
* <tr><td>
* <code>conf.{@link #getChild(String) getChild}("desc").{@link #getValue() getValue}()</code>
* </td><td>{@link ConfigurationException}</td><td>This is a highly fictitious config file</td></tr>
* <tr><td>
* <code>conf.{@link #getChild(String) getChild}("doc:desc").{@link #getValue() getValue}()</code>
* </td><td>This is a highly fictitious config file</td><td>{@link ConfigurationException}</td></tr>
* <tr><td>
* <code>conf.{@link #getChild(String) getChild}("desc").{@link #getNamespace getNamespace}()</code>
* </td><td>&nbsp;</td><td>http://myco.com/documentation"</td></tr>
* </table>
* </p>
* <p>
Expand Down Expand Up @@ -228,7 +229,7 @@ public interface Configuration {
* <em>The order of attributes in this array can not be relied on.</em> As
* with XML, a <code>Configuration</code>'s attributes are an
* <em>unordered</em> set. If your code relies on order, eg
* <tt>conf.getAttributeNames()[0]</tt>, then it is liable to break if a
* <code>conf.getAttributeNames()[0]</code>, then it is liable to break if a
* different XML parser is used.
* </p>
*
Expand Down
5 changes: 4 additions & 1 deletion barcode4j/src/main/java/org/krysalis/barcode4j/configuration/DefaultConfiguration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,10 @@ public void setAttribute(String name, String value) {
}

/**
* @deprecated
* @param name of the attribute
* @param value of the attribute
* @return the value being set
* @deprecated use {@link #setAttribute(String, String)}
*/
@Deprecated
public String addAttribute(String name, String value) {
Expand Down
3 changes: 1 addition & 2 deletions barcode4j/src/main/java/org/krysalis/barcode4j/output/AbstractCanvasProvider.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,7 @@ public abstract class AbstractCanvasProvider implements CanvasProvider {
private final int orientation;

/**
* Main constructor.
* @param orientation the orientation of the barcode
* @param orientation The orientation of the barcode, eg: 0, 90, 180, 270
*/
public AbstractCanvasProvider(int orientation) {
this.orientation = BarcodeDimension.normalizeOrientation(orientation);
Expand Down
3 changes: 3 additions & 0 deletions ...de4j/src/main/java/org/krysalis/barcode4j/output/AbstractXMLGeneratingCanvasProvider.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ public abstract class AbstractXMLGeneratingCanvasProvider extends AbstractCanvas

private DecimalFormat df;

/**
* @param orientation The orientation of the barcode, eg: 0, 90, 180, 270
*/
public AbstractXMLGeneratingCanvasProvider(int orientation) {
super(orientation);
}
Expand Down
30 changes: 11 additions & 19 deletions barcode4j/src/main/java/org/krysalis/barcode4j/output/bitmap/BitmapEncoderRegistry.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,13 @@ public String toString() {
}
}

/**
* Register a new BitmapEncoder implementation.
* @param classname fully qualified classname of the BitmapEncoder implementation
* @param priority lets you define a priority for an encoder. If you want to give an encoder a high priority, assign a value of 100 or higher.
* @param complain will log an error and throw an IllegalArgumentException only if set to true
* @deprecated please use {@link BitmapEncoderRegistry#register(BitmapEncoder, int)}
*/
@Deprecated
private static synchronized void register(String classname, int priority, boolean complain) {
boolean failed = false;
Expand All @@ -107,9 +114,9 @@ private static synchronized void register(String classname, int priority, boolea

/**
* Register a BitmapEncoder implementation.
* @param <T> a class that extends BitmapEncoder
* @param bitmapEncoder an implementation of BitmapEncoder
* @param priority lets you define a priority for an encoder. If you want
* to give an encoder a high priority, assign a value of 100 or higher.
* @param priority lets you define a priority for an encoder. If you want to give an encoder a high priority, assign a value of 100 or higher.
* @return true if the bitmap encoder has been registered
* @author Samael Bate (singingbush)
* created on 23/02/2024
Expand All @@ -122,29 +129,14 @@ public static synchronized <T extends BitmapEncoder> boolean register(final T bi
/**
* Register a new BitmapEncoder implementation.
* @param classname fully qualified classname of the BitmapEncoder implementation
* @param priority lets you define a priority for an encoder. If you want
* to give an encoder a high priority, assign a value of 100 or higher.
* @deprecated please use {@link BitmapEncoderRegistry#register(Class, int)} or {@link BitmapEncoderRegistry#register(BitmapEncoder, int)}
* @param priority lets you define a priority for an encoder. If you want to give an encoder a high priority, assign a value of 100 or higher.
* @deprecated please use {@link BitmapEncoderRegistry#register(BitmapEncoder, int)}
*/
@Deprecated
public static void register(String classname, int priority) {
register(classname, priority, true);
}

/**
* Register a new BitmapEncoder implementation.
* @param bitmapEncoderClass a class that implements BitmapEncoder
* @param priority the priority for an encoder. zero being low and 100 or higher being high
*/
@SuppressWarnings("unused")
public static <BitmapEncoder> void register(final Class<BitmapEncoder> bitmapEncoderClass, final int priority) {
register(bitmapEncoderClass, priority, true);
}

private static <BitmapEncoder> void register(final Class<BitmapEncoder> bitmapEncoderClass, final int priority, final boolean complain) {
register(bitmapEncoderClass.getName(), priority, complain);
}

/**
* Indicates whether a specific BitmapEncoder implementation supports a
* particular MIME type.
Expand Down
13 changes: 8 additions & 5 deletions .../src/main/java/org/krysalis/barcode4j/output/svg/AbstractSVGGeneratingCanvasProvider.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,30 +40,32 @@ public abstract class AbstractSVGGeneratingCanvasProvider extends AbstractXMLGen
* Creates a new AbstractSVGCanvasProvider.
* @param useNamespace Controls whether namespaces should be used
* @param namespacePrefix the namespace prefix to use, null for no prefix
* @param orientation The orientation of the barcode, eg: 0, 90, 180, 270
* @throws BarcodeCanvasSetupException if setting up the provider fails
*/
public AbstractSVGGeneratingCanvasProvider(boolean useNamespace, @Nullable String namespacePrefix, int orientation)
throws BarcodeCanvasSetupException {
public AbstractSVGGeneratingCanvasProvider(boolean useNamespace, @Nullable String namespacePrefix, int orientation) throws BarcodeCanvasSetupException {
super(orientation);
if (!useNamespace && namespacePrefix != null)
if (!useNamespace && namespacePrefix != null) {
throw new IllegalArgumentException("No prefix allow when namespaces are enabled");
}
this.useNamespace = true;
this.prefix = namespacePrefix;
}

/**
* Creates a new AbstractSVGCanvasProvider with namespaces enabled.
* @param namespacePrefix the namespace prefix to use, null for no prefix
* @param orientation The orientation of the barcode, eg: 0, 90, 180, 270
* @throws BarcodeCanvasSetupException if setting up the provider fails
*/
public AbstractSVGGeneratingCanvasProvider(@Nullable String namespacePrefix, int orientation)
throws BarcodeCanvasSetupException {
public AbstractSVGGeneratingCanvasProvider(@Nullable String namespacePrefix, int orientation) throws BarcodeCanvasSetupException {
this(true, namespacePrefix, orientation);
}

/**
* Creates a new AbstractSVGCanvasProvider.
* @param useNamespace Controls whether namespaces should be used
* @param orientation The orientation of the barcode, eg: 0, 90, 180, 270
* @throws BarcodeCanvasSetupException if setting up the provider fails
*/
public AbstractSVGGeneratingCanvasProvider(boolean useNamespace, int orientation) throws BarcodeCanvasSetupException {
Expand All @@ -73,6 +75,7 @@ public AbstractSVGGeneratingCanvasProvider(boolean useNamespace, int orientation
/**
* Creates a new AbstractSVGCanvasProvider with default settings (with
* namespaces, but without namespace prefix).
* @param orientation The orientation of the barcode, eg: 0, 90, 180, 270
* @throws BarcodeCanvasSetupException if setting up the provider fails
*/
public AbstractSVGGeneratingCanvasProvider(int orientation) throws BarcodeCanvasSetupException {
Expand Down

0 comments on commit 3c4a5b5

Please sign in to comment.