commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [05/19] incubator-commonsrdf git commit: conform to -Xdoclint:all
Date Thu, 29 Sep 2016 00:16:41 GMT
conform to -Xdoclint:all


Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/5afd0bd6
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/5afd0bd6
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/5afd0bd6

Branch: refs/heads/jena-jsonld-rdf4j-integration
Commit: 5afd0bd686d717c9b16943bd393fcb49cabd5fd6
Parents: e0d3191
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Wed Sep 28 23:18:45 2016 +0100
Committer: Stian Soiland-Reyes <stain@apache.org>
Committed: Wed Sep 28 23:18:45 2016 +0100

----------------------------------------------------------------------
 .../java/org/apache/commons/rdf/api/Graph.java  |  5 ++
 .../java/org/apache/commons/rdf/api/Quad.java   |  4 +-
 .../commons/rdf/experimental/RDFParser.java     |  8 +--
 .../commons/rdf/experimental/package-info.java  |  1 -
 pom.xml                                         |  4 +-
 .../simple/experimental/AbstractRDFParser.java  | 54 +++++++++++++-------
 .../rdf/simple/experimental/package-info.java   | 11 ++--
 7 files changed, 53 insertions(+), 34 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/api/src/main/java/org/apache/commons/rdf/api/Graph.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/Graph.java b/api/src/main/java/org/apache/commons/rdf/api/Graph.java
index 6106bab..7340e86 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/Graph.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/Graph.java
@@ -158,6 +158,7 @@ public interface Graph extends AutoCloseable,GraphLike<Triple, BlankNodeOrIRI,
I
      * This method is deprecated, use the equivalent method 
      * {@link #stream()} instead. 
      * 
+     * @return A {@link Stream} over all triples.
      */
     @Deprecated
     default Stream<? extends Triple> getTriples() {
@@ -168,6 +169,10 @@ public interface Graph extends AutoCloseable,GraphLike<Triple, BlankNodeOrIRI,
I
      * This method is deprecated, use the equivalent method 
      * {@link #stream(BlankNodeOrIRI, IRI, RDFTerm)} instead.
      * 
+     * @param subject   The triple subject (null is a wildcard)
+     * @param predicate The triple predicate (null is a wildcard)
+     * @param object    The triple object (null is a wildcard)
+     * @return A {@link Stream} over the matched triples.
      */
     @Deprecated    
     default Stream<? extends Triple> getTriples(BlankNodeOrIRI subject, IRI predicate,

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/api/src/main/java/org/apache/commons/rdf/api/Quad.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/Quad.java b/api/src/main/java/org/apache/commons/rdf/api/Quad.java
index 951f593..d52a3c3 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/Quad.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/Quad.java
@@ -43,10 +43,10 @@ public interface Quad extends QuadLike<BlankNodeOrIRI,IRI,RDFTerm,BlankNodeOrIRI
 	 * If {@link Optional#isPresent()}, then the {@link Optional#get()} is
 	 * either a {@link BlankNode} or an {@link IRI}, indicating the
 	 * <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-named-graph">graph
-	 * name of this Quad. If the graph name is not present, e.g. the value is
+	 * name</a> of this Quad. If the graph name is not present, e.g. the value is
 	 * {@link Optional#empty()}, it indicates that this Quad is in the
 	 * <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph">default
-	 * graph.
+	 * graph</a>.
 	 *
 	 * @return If {@link Optional#isPresent()}, the graph name
 	 *         {@link BlankNodeOrIRI} of this quad, otherwise

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java b/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java
index dd6bcf0..d0b8776 100644
--- a/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java
+++ b/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java
@@ -72,7 +72,7 @@ import org.apache.commons.rdf.api.Triple;
  * or a cloned builder with the modified settings applied. 
  * Implementations are however encouraged to be immutable,
  * thread-safe and document this. As an example starting point, see
- * {@link org.apache.commons.rdf.simple.AbstractRDFParserBuilder}.
+ * <code>org.apache.commons.rdf.simple.AbstractRDFParser</code>.
  * <p>
  * Example usage:
  * </p>
@@ -128,7 +128,7 @@ public interface RDFParser {
 	 * <p>
 	 * The character set of the RDFSyntax is assumed to be
 	 * {@link StandardCharsets#UTF_8} unless overridden within the document
-	 * (e.g. <?xml version="1.0" encoding="iso-8859-1"?></code> in
+	 * (e.g. {@code <?xml version="1.0" encoding="iso-8859-1"?>} in
 	 * {@link RDFSyntax#RDFXML}).
 	 * <p>
 	 * This method will override any contentType set with
@@ -259,8 +259,10 @@ public interface RDFParser {
 	 * <p>
 	 * This method is typically called with a functional consumer, for example:
 	 * <pre>
+	 * {@code
 	 * List<Quad> quads = new ArrayList<Quad>;
 	 * parserBuilder.target(quads::add).parse();
+	 * }
 	 * </pre>
 	 * 
 	 * @param consumer
@@ -472,7 +474,7 @@ public interface RDFParser {
 	 * parsing succeeded.
 	 * <p>
 	 * If an exception occurs during parsing, (e.g. {@link IOException} or
-	 * {@link org.apache.commons.rdf.simple.RDFParseException}), 
+	 * <code>org.apache.commons.rdf.simple.experimental.RDFParseException</code>),

 	 * it should be indicated as the
 	 * {@link java.util.concurrent.ExecutionException#getCause()} in the
 	 * {@link java.util.concurrent.ExecutionException} thrown on

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java b/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java
index 5f24ddc..5b9e489 100644
--- a/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java
+++ b/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java
@@ -24,7 +24,6 @@
  * <p>
  * When class/interface has stabilized, it will move to the
  * {@link org.apache.commons.rdf.api} package.
- * <p>
  * <ul>
  * <li>{@link RDFParser} - a builder-like interface for parsing RDF to a
  * {@link org.apache.commons.rdf.api.Graph} or

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index f9b85fc..4920284 100644
--- a/pom.xml
+++ b/pom.xml
@@ -281,7 +281,7 @@
                     </execution>
                 </executions>
                 <configuration>
-                    <additionalparam>-Xdoclint:none</additionalparam>
+                    <additionalparam>-Xdoclint:all</additionalparam>
                 </configuration>
             </plugin>
             <!--
@@ -448,7 +448,7 @@
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <configuration>
-                 <additionalparam>-Xdoclint:none</additionalparam>
+                 <additionalparam>-Xdoclint:all</additionalparam>
              </configuration>
              <reportSets>
                <reportSet><!-- by default, id = "default" -->

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
----------------------------------------------------------------------
diff --git a/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
b/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
index 8111f09..9b07699 100644
--- a/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
+++ b/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
@@ -67,6 +67,9 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 
 	/**
 	 * Get the set {@link RDFTermFactory}, if any.
+	 * 
+	 * @return The {@link RDFTermFactory} to use, or {@link Optional#empty()} if
+	 *         it has not been set
 	 */
 	public Optional<RDFTermFactory> getRdfTermFactory() {
 		return rdfTermFactory;
@@ -75,9 +78,11 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	/**
 	 * Get the set content-type {@link RDFSyntax}, if any.
 	 * <p>
-	 * If this is {@link Optional#isPresent()}, then 
-	 * {@link #getContentType()} contains the 
-	 * value of {@link RDFSyntax#mediaType}. 
+	 * If this is {@link Optional#isPresent()}, then {@link #getContentType()}
+	 * contains the value of {@link RDFSyntax#mediaType}.
+	 * 
+	 * @return The {@link RDFSyntax} of the content type, or
+	 *         {@link Optional#empty()} if it has not been set
 	 */
 	public Optional<RDFSyntax> getContentTypeSyntax() {
 		return contentTypeSyntax;
@@ -86,11 +91,13 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	/**
 	 * Get the set content-type String, if any.
 	 * <p>
-	 * If this is {@link Optional#isPresent()} and 
-	 * is recognized by {@link RDFSyntax#byMediaType(String)}, then
-	 * the corresponding {@link RDFSyntax} is set on 
-	 * {@link #getContentType()}, otherwise that is
-	 * {@link Optional#empty()}. 
+	 * If this is {@link Optional#isPresent()} and is recognized by
+	 * {@link RDFSyntax#byMediaType(String)}, then the corresponding
+	 * {@link RDFSyntax} is set on {@link #getContentType()}, otherwise that is
+	 * {@link Optional#empty()}.
+	 * 
+	 * @return The Content-Type IANA media type, e.g. <code>text/turtle</code>,
+	 *         or {@link Optional#empty()} if it has not been set
 	 */
 	public final Optional<String> getContentType() {
 		return contentType;
@@ -99,8 +106,11 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	/**
 	 * Get the target to consume parsed Quads.
 	 * <p>
-	 * From the call to {@link #parseSynchronusly()}, this
-	 * method is always {@link Optional#isPresent()}.
+	 * From the call to {@link #parseSynchronusly()}, this will be a
+	 * non-<code>null</code> value (as a target is a required setting).
+	 * 
+	 * @return The target consumer of {@link Quad}s, or <code>null</code> if it
+	 *         has not yet been set.
 	 * 
 	 */	
 	public Consumer<Quad> getTarget() {
@@ -143,8 +153,8 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	
 	/**
 	 * Get the set base {@link IRI}, if present.
-	 * <p>
 	 * 
+	 * @return The base {@link IRI}, or {@link Optional#empty()} if it has not been set
 	 */	
 	public Optional<IRI> getBase() {
 		return base;
@@ -156,6 +166,8 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	 * If this is {@link Optional#isPresent()}, then 
 	 * {@link #getSourceFile()} and {@link #getSourceIri()}
 	 * are {@link Optional#empty()}.
+	 * 
+	 * @return The source {@link InputStream}, or {@link Optional#empty()} if it has not been
set
 	 */
 	public Optional<InputStream> getSourceInputStream() {
 		return sourceInputStream;
@@ -167,6 +179,8 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	 * If this is {@link Optional#isPresent()}, then 
 	 * {@link #getSourceInputStream()} and {@link #getSourceIri()}
 	 * are {@link Optional#empty()}.
+	 *
+	 * @return The source {@link Path}, or {@link Optional#empty()} if it has not been set
 	 */	
 	public Optional<Path> getSourceFile() {
 		return sourceFile;
@@ -176,8 +190,10 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	 * Get the set source {@link Path}.
 	 * <p>
 	 * If this is {@link Optional#isPresent()}, then 
-	 * {@link #getSourceInputStream()} and {@link #getSourceInputStream()()}
+	 * {@link #getSourceInputStream()} and {@link #getSourceInputStream()}
 	 * are {@link Optional#empty()}.
+	 * 
+ 	 * @return The source {@link IRI}, or {@link Optional#empty()} if it has not been set
 	 */		
 	public Optional<IRI> getSourceIri() {
 		return sourceIri;
@@ -283,11 +299,12 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	/**
 	 * Check if an iri is absolute.
 	 * <p>
-	 * Used by {@link #source(String)} and {@link #base(String)}
+	 * Used by {@link #source(String)} and {@link #base(String)}.
 	 * 
-	 * @param iri
+	 * @param iri IRI to check
+	 * @throws IllegalArgumentException If the IRI is not absolute
 	 */
-	protected void checkIsAbsolute(IRI iri) {
+	protected void checkIsAbsolute(IRI iri) throws IllegalArgumentException {
 		if (!URI.create(iri.getIRIString()).isAbsolute()) {
 			throw new IllegalArgumentException("IRI is not absolute: " + iri);
 		}
@@ -327,7 +344,7 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 	 * 
 	 * @throws IllegalStateException if base is required, but not set.
 	 */
-	protected void checkBaseRequired() {
+	protected void checkBaseRequired() throws IllegalStateException {
 		if (!base.isPresent() && sourceInputStream.isPresent()
 				&& !contentTypeSyntax.filter(t -> t == RDFSyntax.NQUADS || t == RDFSyntax.NTRIPLES).isPresent())
{
 			throw new IllegalStateException("base iri required for inputstream source");
@@ -347,12 +364,11 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
 		sourceFile = Optional.empty();
 	}
 
-
 	/**
-	 * Reset all optional target* fields to Optional.empty()</code>
+	 * Reset all optional target* fields to {@link Optional#empty()}.
 	 * <p>
 	 * Note that the consumer set for {@link #getTarget()} is
-	 * NOT reset.
+	 * <strong>note</strong> reset.
 	 * <p>
 	 * Subclasses should override this and call <code>super.resetTarget()</code>
 	 * if they need to reset any additional target* fields.

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
----------------------------------------------------------------------
diff --git a/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
b/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
index 5196f42..c5f4a42 100644
--- a/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
+++ b/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
@@ -18,17 +18,14 @@
 /**
  * Experimental Commons RDF Simple implementations.
  * <p>
- * Classes in this package should be considered <strong>at
- * risk</strong>; they might change or be removed in the next minor update of
- * Commons RDF.
+ * Classes in this package should be considered <strong>at risk</strong>; they
+ * might change or be removed in the next minor update of Commons RDF.
  * <p>
  * When a class has stabilized, it will move to the
  * {@link org.apache.commons.rdf.simple} package.
- * <p>
  * <ul>
- * <li>{@link AbstractRDFParser} - an abstract helper class
- * for implementations of 
- * {@link org.apache.commons.rdf.api.experimental.RDFParser}.</li>
+ * <li>{@link AbstractRDFParser} - an abstract helper class for implementations
+ * of {@link org.apache.commons.rdf.experimental.RDFParser}.</li>
  * </ul>
  */
 package org.apache.commons.rdf.simple.experimental;
\ No newline at end of file


Mime
View raw message