more javadocs

(cherry picked from commit a0f71c49c91a9f3cc5c3fb3ad61303769d53d45d)

Author: sammefford

src/main/java/com/marklogic/client/semantics/GraphManager.java

@@ -36,7 +36,7 @@
  *
  * <p>For example:</p>
  *
- * <p>If you have a file called "example.ttl" containing one triple in turtle
+ * <p>If you have a file called "example.nt" containing one triple in turtle
  * mimetype:</p>
  *
  * <pre>    &lt;http://example.org/subject1&gt; &lt;http://example.org/predicate1&gt; &lt;http://example.org/object1&gt; .</pre>
@@ -45,7 +45,7 @@
  * like so:</p>
  *
  * <pre>    GraphManager graphMgr = databaseClient.newGraphManager();
- *    FileHandle fileHandle = new FileHandle(new File("example.ttl")).withMimetype(RDFMimeTypes.NTRIPLES);
+ *    FileHandle fileHandle = new FileHandle(new File("example.nt")).withMimetype(RDFMimeTypes.NTRIPLES);
  *    graphMgr.write("myExample/graphUri", fileHandle);
  * </pre>
  *

src/main/java/com/marklogic/client/semantics/SPARQLBinding.java

@@ -18,9 +18,11 @@
 import java.util.Locale;
 
 /**
- * Represents a binding name, value, and type or language tag.
- * For details about semantics in MarkLogic see
- * {@link https://docs.marklogic.com/guide/semantics Semantics Developer's Guide}
+ * <p>Represents a binding name, value, and type or language tag.</p>
+ *
+ * <p>For details about RDF, SPARQL, and semantics in MarkLogic see the <a
+ * href="https://docs.marklogic.com/guide/semantics" target="_top">Semantics
+ * Developer's Guide</a>.
  */
 public interface SPARQLBinding {
     public String getName();

src/main/java/com/marklogic/client/semantics/SPARQLBindings.java

@@ -21,8 +21,35 @@
 
 /** <p>Represents binding names and values to be sent with a SPARQL Query.
  * Available for situations where {@link SPARQLQueryDefinition#withBinding
- * SPARQLQueryDefinition.withBinding} methods are not enough.  For example
- * usage, see {@link SPARQLQueryManager}.</p>
+ * SPARQLQueryDefinition.withBinding} methods are not enough.
+ *
+ * <p>Example matching an iri:</p>
+ *
+ * <pre>    graphMgr.setDefaultMimetype(RDFMimeTypes.NTRIPLES);
+ *    graphMgr.writeAs("http://example.org",
+ *        "&lt;http://example.org/s1&gt; &lt;http://example.org/p1&gt; &lt;http://example.org/object1&gt; .\n" +
+ *        "&lt;http://example.org/s2&gt; &lt;http://example.org/p2&gt; \"object2\" .\n" +
+ *        "&lt;http://example.org/s3&gt; &lt;http://example.org/p3&gt; \"object3\"@en .");
+ *    String select = "SELECT * WHERE { ?s ?p ?o }";
+ *    SPARQLQueryDefinition qdef = sparqlMgr.newQueryDefinition(select);
+ *    SPARQLBindings bindings = qdef.getBindings();
+ *    bindings.bind("o", "http://example.org/object1");
+ *    JacksonHandle results = sparqlMgr.executeSelect(qdef, new JacksonHandle());</pre>
+ *
+ * <p>Example matching a string with a language tag (re-using data and variables above):</p>
+ *
+ * <pre>    qdef = sparqlMgr.newQueryDefinition(select);
+ *    bindings = qdef.getBindings();
+ *    bindings.bind("o", "object2", RDFTypes.STRING);
+ *    results = sparqlMgr.executeSelect(qdef, new JacksonHandle());</pre>
+ *
+ *
+ * <p>Example matching a string with a language tag (re-using data and variables above):</p>
+ *
+ * <pre>    qdef = sparqlMgr.newQueryDefinition(select);
+ *    bindings = qdef.getBindings();
+ *    bindings.bind("o", "object3", new Locale("en"));
+ *    results = sparqlMgr.executeSelect(qdef, new JacksonHandle());</pre>
  *
  * <p>For more about RDF literals, see <a
  * href="http://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal"
@@ -33,26 +60,35 @@
  * Developer's Guide</a>.
  */
 public interface SPARQLBindings extends Map<String, List<SPARQLBinding>> {
-    /** Bind a variable of type iri.
+    /** <p>Bind a variable of type iri.</p>
+     *
      * @param name the bound variable name
-     * @param value the value of type iri
+     * @param value the iri value
      *
      * @return this instance (for method chaining)
      */
     public SPARQLBindings bind(String name, String value);
-    /** Bind a variable of specified type.
+
+    /** <p>Bind a variable of specified type.</p>
+     *
      * @param name the bound variable name
-     * @param value the value of type iri
-     * @param datatype the type
+     * @param value the value of the literal
+     * @param datatype the literal type
      *
      * @return this instance (for method chaining)
      */
     public SPARQLBindings bind(String name, String value, RDFTypes datatype);
-    /** Bind a variable of type
+
+    /** <p>Bind a variable of type
      * http://www.w3.org/1999/02/22-rdf-syntax-ns#langString with the specified
-     * language tag.  Note that we call <a
-     * href="http://docs.oracle.com/javase/7/docs/api/java/util/Locale.html#toLanguageTag%28%29"
-     * >Locale.toLanguageTag()</a>
-     * to get compliant IETF BCP 47 language tags. */
+     * language tag.  Note that we call {@link Locale#toLanguageTag}
+     * to get compliant IETF BCP 47 language tags.</p>
+     *
+     * @param name the bound variable name
+     * @param value the value as a string
+     * @param languageTag the language and regional modifiers compliant with BCP-47
+     *
+     * @return this instance (for method chaining)
+     */
     public SPARQLBindings bind(String name, String value, Locale languageTag);
 };