This is an automated email from the ASF dual-hosted git repository.
lewismc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/any23.git
The following commit(s) were added to refs/heads/master by this push:
new 9a794f7 ANY23-426 Address Javadoc WARNING's (#146)
9a794f7 is described below
commit 9a794f7701add75b175df6204dfff4021fb637b2
Author: Lewis John McGibbney <[email protected]>
AuthorDate: Thu Sep 26 06:36:51 2019 -0700
ANY23-426 Address Javadoc WARNING's (#146)
* ANY23-426 Address Javadoc WARNING's
---
.../org/apache/any23/configuration/Setting.java | 14 +++++++------
.../org/apache/any23/configuration/Settings.java | 24 ++++++++++++++--------
.../org/apache/any23/writer/WriterFactory.java | 4 ++++
.../any23/extractor/yaml/ElementsProcessor.java | 8 ++++----
.../java/org/apache/any23/http/HTTPClient.java | 4 ++--
.../main/java/org/apache/any23/rdf/RDFUtils.java | 10 ++++-----
.../java/org/apache/any23/util/StreamUtils.java | 12 +++++++----
.../any23/extractor/csv/CSVReaderBuilder.java | 4 ++--
.../apache/any23/plugin/crawler/SiteCrawler.java | 10 +++++----
.../main/java/org/apache/any23/vocab/Excel.java | 7 ++++++-
pom.xml | 20 ++++++++++++++++++
.../servlet/conneg/ContentTypeNegotiator.java | 4 ++--
.../any23/servlet/conneg/MediaRangeSpec.java | 4 ++--
13 files changed, 84 insertions(+), 41 deletions(-)
diff --git a/api/src/main/java/org/apache/any23/configuration/Setting.java
b/api/src/main/java/org/apache/any23/configuration/Setting.java
index 0fc7919..0e17209 100644
--- a/api/src/main/java/org/apache/any23/configuration/Setting.java
+++ b/api/src/main/java/org/apache/any23/configuration/Setting.java
@@ -113,6 +113,8 @@ public abstract class Setting<V> implements Cloneable {
}
/**
+ * @param setting a setting that may or may not have the same key as this
setting
+ * @param <S> the type of the supplied setting
* @return this setting, if this setting has the same key as the supplied
setting
*/
@SuppressWarnings("unchecked")
@@ -121,6 +123,7 @@ public abstract class Setting<V> implements Cloneable {
}
/**
+ * @param newValue a value for a new setting
* @return a new {@link Setting} object with this setting's key and the
supplied value.
*
* @throws IllegalArgumentException if the new value was invalid, as
determined by:
@@ -237,6 +240,7 @@ public abstract class Setting<V> implements Cloneable {
/**
* Convenience method to create a new setting with the specified
identifier,
* value type, and default value.
+ * @param <V> generic setting value type
* @param identifier the identifier for this setting
* @param valueType the value type for this setting
* @param defaultValue the default value for this setting
@@ -248,8 +252,6 @@ public abstract class Setting<V> implements Cloneable {
return new Impl<>(identifier, valueType, defaultValue);
}
-
-
///////////////////////////////////////
// Private static helpers
///////////////////////////////////////
@@ -314,16 +316,16 @@ public abstract class Setting<V> implements Cloneable {
for (;;) {
Type superclass = rawType.getGenericSuperclass();
if (superclass instanceof ParameterizedType) {
- rawType = (Class)((ParameterizedType) superclass).getRawType();
+ rawType = (Class<?>)((ParameterizedType)
superclass).getRawType();
Type[] args = ((ParameterizedType)
superclass).getActualTypeArguments();
if (Setting.class.equals(rawType)) {
Type type = args[0];
type = mapping.getOrDefault(type, type);
if (type instanceof Class) {
- if (((Class) type).isArray()) {
+ if (((Class<?>) type).isArray()) {
throw new IllegalArgumentException(identifier + "
value class must be immutable");
- } else if (((Class) type).getTypeParameters().length
!= 0) {
- throw new IllegalArgumentException(identifier + "
setting must fill in type parameters for " + ((Class) type).toGenericString());
+ } else if (((Class<?>)
type).getTypeParameters().length != 0) {
+ throw new IllegalArgumentException(identifier + "
setting must fill in type parameters for " + ((Class<?>)
type).toGenericString());
}
} else if (type instanceof GenericArrayType) {
throw new IllegalArgumentException(identifier + "
value class must be immutable");
diff --git a/api/src/main/java/org/apache/any23/configuration/Settings.java
b/api/src/main/java/org/apache/any23/configuration/Settings.java
index e4cb115..2be73fa 100644
--- a/api/src/main/java/org/apache/any23/configuration/Settings.java
+++ b/api/src/main/java/org/apache/any23/configuration/Settings.java
@@ -52,13 +52,14 @@ public final class Settings extends AbstractSet<Setting<?>>
{
}
/**
- * Returns the setting with the same setting key as the supplied setting,
if present.
- * <br><br>
* This method is semantically equivalent to:
* <br><br>
* <pre>
* {@code find(setting.getIdentifier()).flatMap(s -> s.as(setting))}
* </pre>
+ * @param <S> generic setting type
+ * @param setting a setting key
+ * @return the setting with the same setting key as the supplied setting,
if present.
*/
public <S extends Setting<?>> Optional<S> find(S setting) {
Setting<?> found = values.get(setting.getIdentifier());
@@ -66,20 +67,20 @@ public final class Settings extends AbstractSet<Setting<?>>
{
}
/**
- * Returns the value set for {@code defaultSetting}'s key, if present.
- * Otherwise, returns {@code defaultSetting}'s value.
- * <br><br>
* This method is semantically equivalent to:
* <br><br>
* <pre>
* {@code find(defaultSetting).orElse(defaultSetting).getValue()}
* </pre>
+ * @param <E> generic setting type
+ * @param defaultSetting a default key for which to obtain a value set
+ * @return the value set for {@code defaultSetting}'s key, if present.
+ * Otherwise, returns {@code defaultSetting}'s value.
*/
public <E> E get(Setting<E> defaultSetting) {
return find(defaultSetting).orElse(defaultSetting).getValue();
}
-
///////////////////////////////////////
// AbstractSet overrides
///////////////////////////////////////
@@ -108,20 +109,24 @@ public final class Settings extends
AbstractSet<Setting<?>> {
/**
* Returns an empty {@link Settings} object.
+ * @return an empty {@link Settings} object
*/
public static Settings of() {
return EMPTY_SETTINGS;
}
/**
- * Returns a singleton {@link Settings} object, containing only the
supplied setting.
+ * Returns a singleton {@link Settings} object, containing only the
supplied Setting.
+ * @param s one {@link org.apache.any23.configuration.Setting}
+ * @return a {@link Settings} object containing the supplied Setting.
*/
public static Settings of(Setting<?> s) {
return new Settings(Collections.singletonMap(s.getIdentifier(), s));
}
/**
- * Returns a {@link Settings} object containing the supplied settings.
+ * @param settings one or more {@link
org.apache.any23.configuration.Setting}'s
+ * @return a {@link Settings} object containing the supplied settings.
* For any two settings having the same key, the first will be overwritten
by the second.
* @throws IllegalArgumentException if any two settings have the same
identifier
*/
@@ -132,7 +137,8 @@ public final class Settings extends AbstractSet<Setting<?>>
{
}
/**
- * Returns a {@link Settings} object containing the supplied settings.
+ * @param c a populated {@link java.util.Collection} of {@link
org.apache.any23.configuration.Setting}'s
+ * @return a {@link Settings} object containing the supplied settings.
* @throws IllegalArgumentException if any two settings have the same
identifier
*/
public static Settings of(Collection<? extends Setting<?>> c) {
diff --git a/api/src/main/java/org/apache/any23/writer/WriterFactory.java
b/api/src/main/java/org/apache/any23/writer/WriterFactory.java
index 060177b..353ba11 100644
--- a/api/src/main/java/org/apache/any23/writer/WriterFactory.java
+++ b/api/src/main/java/org/apache/any23/writer/WriterFactory.java
@@ -32,6 +32,7 @@ public interface WriterFactory {
/**
* @deprecated since 2.3. Use {@link
TripleWriterFactory#getTripleFormat()} instead.
+ * @return the {@link org.eclipse.rdf4j.rio.RDFFormat} being handled
*/
@Deprecated
RDFFormat getRdfFormat();
@@ -40,12 +41,15 @@ public interface WriterFactory {
/**
* @deprecated since 2.3. Use {@link
TripleWriterFactory#getTripleFormat()}.{@link TripleFormat#getMimeType()
getMimeType()} instead.
+ * @return a String representing the Mimetype being handled in this Writer
*/
@Deprecated
String getMimeType();
/**
* @deprecated since 2.3. Use {@link
TripleWriterFactory#getTripleWriter(OutputStream, Settings)} instead.
+ * @param os a {@link java.io.OutputStream} to be written to the
FormatWriter handler
+ * @return a {@link org.apache.any23.writer.FormatWriter} ready to be
implemented
*/
@Deprecated
FormatWriter getRdfWriter(OutputStream os);
diff --git
a/core/src/main/java/org/apache/any23/extractor/yaml/ElementsProcessor.java
b/core/src/main/java/org/apache/any23/extractor/yaml/ElementsProcessor.java
index 75c6611..5b36128 100644
--- a/core/src/main/java/org/apache/any23/extractor/yaml/ElementsProcessor.java
+++ b/core/src/main/java/org/apache/any23/extractor/yaml/ElementsProcessor.java
@@ -121,13 +121,13 @@ public class ElementsProcessor {
}
/**
- * This method creates a map with non bnode root.
+ * This method processes a map with non bnode root.
*
* If a map has instantiated root (not a blank node) it is simpler to
create SPARQL query.
*
- * @param ns
- * @param object
- * @param parentNode
+ * @param ns the namespace to associated with statements
+ * @param object a populated {@link java.util.Map}
+ * @param parentNode a {@link org.eclipse.rdf4j.model.Value} subject node
to use in the new statement
* @return instance of {@link ModelHolder}.
*/
protected ModelHolder processMap(IRI ns, Map<String, Object> object, Value
parentNode) {
diff --git a/core/src/main/java/org/apache/any23/http/HTTPClient.java
b/core/src/main/java/org/apache/any23/http/HTTPClient.java
index 3f08975..cf0f1e7 100644
--- a/core/src/main/java/org/apache/any23/http/HTTPClient.java
+++ b/core/src/main/java/org/apache/any23/http/HTTPClient.java
@@ -54,7 +54,7 @@ public interface HTTPClient {
/**
* The value of the Content-Type header reported by the server.
- * Can be <tt>null</tt>.
+ * Can be <code>null</code>.
*
* @return the content type as string.
*/
@@ -68,7 +68,7 @@ public interface HTTPClient {
/**
* Returns the actual IRI from which the document was fetched.
* This might differ from the IRI passed to openInputStream()
- * if a redirect was performed. A return value of <tt>null</tt>
+ * if a redirect was performed. A return value of <code>null</code>
* means that the IRI is unchanged and the original IRI was used.
*
* @return actual document IRI.
diff --git a/core/src/main/java/org/apache/any23/rdf/RDFUtils.java
b/core/src/main/java/org/apache/any23/rdf/RDFUtils.java
index 552d61f..14aeab3 100644
--- a/core/src/main/java/org/apache/any23/rdf/RDFUtils.java
+++ b/core/src/main/java/org/apache/any23/rdf/RDFUtils.java
@@ -537,7 +537,7 @@ public class RDFUtils {
/**
* {@link #makeIRI(java.lang.String, org.eclipse.rdf4j.model.IRI, boolean)
}.
- * @param docUri
+ * @param docUri It is a namespace. If it ends with '/' character than
stays unchanged otherwise the hash character '#' is added to the end.
* @return instance of {@link Resource}.
*/
public static Resource makeIRI(IRI docUri) {
@@ -546,8 +546,8 @@ public class RDFUtils {
/**
* {@link #makeIRI(java.lang.String, org.eclipse.rdf4j.model.IRI, boolean)
}.
- * @param type
- * @param docIRI
+ * @param type This argument is converted following Java naming
conventions with {@link StringUtils#implementJavaNaming(java.lang.String) }.
+ * @param docIRI It is a namespace. If it ends with '/' character than
stays unchanged otherwise the hash character '#' is added to the end.
* @return instance of {@link Resource}.
*/
public static Resource makeIRI(String type, IRI docIRI) {
@@ -561,7 +561,7 @@ public class RDFUtils {
*
* @param type This argument is converted following Java naming
conventions with {@link StringUtils#implementJavaNaming(java.lang.String) }.
* @param docIRI It is a namespace. If it ends with '/' character than
stays unchanged otherwise the hash character '#' is added to the end.
- * @param addId If argument is <b>TRUE</b> than the node identifier is
added to the end formated <tt>'_{int}'</tt>.
+ * @param addId If argument is <b>TRUE</b> than the node identifier is
added to the end formated <code>'_{int}'</code>.
* @return instance of {@link Resource}.
*/
public static Resource makeIRI(String type, IRI docIRI, boolean addId) {
@@ -594,7 +594,7 @@ public class RDFUtils {
* If string value expresses valid IRI than {@link IRI} is created.
Otherwise method
* creates simple {@link Literal} xsd:string.
*
- * @param inString
+ * @param inString an input string to manifest as {@link
org.eclipse.rdf4j.model.Value}
* @return either {@link IRI} or {@link Literal}.
*/
public static Value makeIRI(String inString) {
diff --git a/core/src/main/java/org/apache/any23/util/StreamUtils.java
b/core/src/main/java/org/apache/any23/util/StreamUtils.java
index a456655..f2b227a 100644
--- a/core/src/main/java/org/apache/any23/util/StreamUtils.java
+++ b/core/src/main/java/org/apache/any23/util/StreamUtils.java
@@ -132,10 +132,14 @@ public class StreamUtils {
}
/**
- * Converts a {@link org.w3c.dom.Document} to an
- * {@link java.io.InputStream}
- * @throws TransformerFactoryConfigurationError
- * @throws TransformerConfigurationException
+ * Converts a {@link org.w3c.dom.Document} to an {@link
java.io.InputStream}
+ * @param doc the {@link org.w3c.dom.Document} to convert
+ * @return an {@link java.io.InputStream} representing the contents of the
+ * input {@link org.w3c.dom.Document}
+ * @throws TransformerFactoryConfigurationError thrown when there is a
problem
+ * with configuration with the Transformer Factories
+ * @throws TransformerConfigurationException thrown when a serious
+ * configuration error exists
*/
public static InputStream documentToInputStream(Document doc)
throws TransformerConfigurationException,
TransformerFactoryConfigurationError {
diff --git
a/csvutils/src/main/java/org/apache/any23/extractor/csv/CSVReaderBuilder.java
b/csvutils/src/main/java/org/apache/any23/extractor/csv/CSVReaderBuilder.java
index 87d764d..9ecb6b9 100644
---
a/csvutils/src/main/java/org/apache/any23/extractor/csv/CSVReaderBuilder.java
+++
b/csvutils/src/main/java/org/apache/any23/extractor/csv/CSVReaderBuilder.java
@@ -62,7 +62,7 @@ public class CSVReaderBuilder {
*
* @param is {@link InputStream} of the <i>CSV</i> file where guess the
configuration.
* @return a {@link CSVParser}
- * @throws java.io.IOException
+ * @throws java.io.IOException if there is an error building the parser
*/
public static CSVParser build(InputStream is) throws IOException {
CSVFormat bestStrategy = getBestStrategy(is);
@@ -77,7 +77,7 @@ public class CSVReaderBuilder {
* @param is input stream to be verified.
* @return <code>true</code> if the given <code>is</code> input stream
contains a <i>CSV</i> content.
* <code>false</code> otherwise.
- * @throws IOException
+ * @throws IOException if there is an error processing the input stream
*/
public static boolean isCSV(InputStream is) throws IOException {
return getBestStrategy(is) != null;
diff --git
a/plugins/basic-crawler/src/main/java/org/apache/any23/plugin/crawler/SiteCrawler.java
b/plugins/basic-crawler/src/main/java/org/apache/any23/plugin/crawler/SiteCrawler.java
index dbc836d..7fd0d48 100644
---
a/plugins/basic-crawler/src/main/java/org/apache/any23/plugin/crawler/SiteCrawler.java
+++
b/plugins/basic-crawler/src/main/java/org/apache/any23/plugin/crawler/SiteCrawler.java
@@ -204,7 +204,8 @@ public class SiteCrawler {
/**
* Registers a {@link CrawlerListener} to this crawler.
*
- * @param listener
+ * @param listener a {@link
org.apache.any23.plugin.crawler.CrawlerListener}
+ * implementation which listens for page discovery
*/
public void addListener(CrawlerListener listener) {
listeners.add(listener);
@@ -213,7 +214,8 @@ public class SiteCrawler {
/**
* Deregisters a {@link CrawlerListener} from this crawler.
*
- * @param listener
+ * @param listener a {@link
org.apache.any23.plugin.crawler.CrawlerListener}
+ * implementation which listens for page discovery
*/
public void removeListener(CrawlerListener listener) {
listeners.remove(listener);
@@ -225,7 +227,7 @@ public class SiteCrawler {
* @param seed the starting URL for the crawler process.
* @param filters filters to be applied to the crawler process. Can be
<code>null</code>.
* @param wait if <code>true</code> the process will wait for the crawler
termination.
- * @throws Exception
+ * @throws Exception if an error occurred during crawler initiation
*/
public synchronized void start(
final URL seed, final Pattern filters, final boolean wait
@@ -252,7 +254,7 @@ public class SiteCrawler {
*
* @param seed the starting URL for the crawler process.
* @param wait if <code>true</code> the process will wait for the crawler
termination.
- * @throws Exception
+ * @throws Exception if an error occurred during crawler initiation
*/
public void start(final URL seed, final boolean wait) throws Exception {
start(seed, defaultFilters, wait);
diff --git
a/plugins/office-scraper/src/main/java/org/apache/any23/vocab/Excel.java
b/plugins/office-scraper/src/main/java/org/apache/any23/vocab/Excel.java
index 3295469..7fc5bbc 100644
--- a/plugins/office-scraper/src/main/java/org/apache/any23/vocab/Excel.java
+++ b/plugins/office-scraper/src/main/java/org/apache/any23/vocab/Excel.java
@@ -117,13 +117,18 @@ public class Excel extends Vocabulary {
return InstanceHolder.instance;
}
+ /**
+ *
+ * @param localName resource label to create
+ * @return the new IRI instance.
+ */
public IRI createResource(String localName) {
return createProperty(NS, localName);
}
/**
*
- * @param localName
+ * @param localName property label to create
* @return the new IRI instance.
*/
public IRI createProperty(String localName) {
diff --git a/pom.xml b/pom.xml
index 3a63d24..c8f5fb6 100644
--- a/pom.xml
+++ b/pom.xml
@@ -738,6 +738,21 @@
</pluginManagement>
<plugins>
+
+ <!-- Javadoc plugin. -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>${maven-javadoc-plugin.version}</version>
+ <configuration>
+ <!--
+ | Apple's JVM sometimes requires more memory
+ -->
+ <additionalJOption>-J-Xmx1024m</additionalJOption>
+ <source>8</source>
+ </configuration>
+ </plugin>
+
<!-- Drop inherited behavior (i.e. don't put any more default LICENSE
and NOTICE files in all artifacts) -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
@@ -898,6 +913,7 @@
| Apple's JVM sometimes requires more memory
-->
<additionalJOption>-J-Xmx1024m</additionalJOption>
+ <source>8</source>
</configuration>
</plugin>
@@ -1037,6 +1053,7 @@
<goal>jar</goal>
</goals>
<configuration>
+ <source>8</source>
<quiet>true</quiet>
<archive>
<manifest>
@@ -1130,6 +1147,9 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${maven-javadoc-plugin.version}</version>
+ <configuration>
+ <source>8</source>
+ </configuration>
<reportSets>
<reportSet>
<reports>
diff --git
a/service/src/main/java/org/apache/any23/servlet/conneg/ContentTypeNegotiator.java
b/service/src/main/java/org/apache/any23/servlet/conneg/ContentTypeNegotiator.java
index c0e1de3..8546f96 100644
---
a/service/src/main/java/org/apache/any23/servlet/conneg/ContentTypeNegotiator.java
+++
b/service/src/main/java/org/apache/any23/servlet/conneg/ContentTypeNegotiator.java
@@ -94,9 +94,9 @@ public class ContentTypeNegotiator {
* faulty Accept headers.
*
* @param userAgentString A pattern to be matched against the
User-Agent header;
- * <tt>null</tt> means regardless of User-Agent
+ * <code>null</code> means regardless of
User-Agent
* @param originalAcceptHeader Only override the Accept header if the user
agent
- * sends this header; <tt>null</tt> means
always override
+ * sends this header; <code>null</code> means
always override
* @param newAcceptHeader The Accept header to be used instead
*/
protected void addUserAgentOverride(
diff --git
a/service/src/main/java/org/apache/any23/servlet/conneg/MediaRangeSpec.java
b/service/src/main/java/org/apache/any23/servlet/conneg/MediaRangeSpec.java
index b71e3ee..f4923fc 100644
--- a/service/src/main/java/org/apache/any23/servlet/conneg/MediaRangeSpec.java
+++ b/service/src/main/java/org/apache/any23/servlet/conneg/MediaRangeSpec.java
@@ -79,7 +79,7 @@ public class MediaRangeSpec {
}
/**
- * Parses a media type from a string such as
<tt>text/html;charset=utf-8;q=0.9</tt>.
+ * Parses a media type from a string such as
<code>text/html;charset=utf-8;q=0.9</code>.
* @param mediaType input string from which to extract mediaType
* @return {@link org.apache.any23.servlet.conneg.MediaRangeSpec}
*/
@@ -92,7 +92,7 @@ public class MediaRangeSpec {
}
/**
- * Parses a media range from a string such as
<tt>text/*;charset=utf-8;q=0.9</tt>.
+ * Parses a media range from a string such as
<code>text/*;charset=utf-8;q=0.9</code>.
* Unlike simple media types, media ranges may include wildcards.
* @param mediaRange input string from which to extract media range
* @return {@link org.apache.any23.servlet.conneg.MediaRangeSpec}
