Repository: incubator-commonsrdf Updated Branches: refs/heads/jena a423c41ac -> b0c55bda2
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 Commit: 5afd0bd686d717c9b16943bd393fcb49cabd5fd6 Parents: e0d3191 Author: Stian Soiland-Reyes <st...@apache.org> Authored: Wed Sep 28 23:18:45 2016 +0100 Committer: Stian Soiland-Reyes <st...@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
