CLJ-1190 - move clojure.api.API to clojure.java.api.Clojure. add java…

…doc for clojure.lang, clojure.lang.IFn, clojure.java.api.Clojure. add ant target to generate javadoc for the API. Signed-off-by: Stuart Halloway <stu@cognitect.com>
clojure · Jan 11, 2014 · 43873e4 · 43873e4
1 parent f7215fd
commit 43873e4
Show file tree

Hide file tree

Showing 6 changed files with 106 additions and 26 deletions.
diff --git a/build.xml b/build.xml
@@ -130,7 +130,26 @@
     </jar>
     <copy file="${clojure_jar}" tofile="${clojure_noversion_jar}"/>
   </target>
-
+
+  <target name="javadoc"
+	  description="Creates javadoc for Clojure API.">
+    <copy file="src/jvm/clojure/lang/IFn.java" tofile="target/tmpjd/IFn.java"/>
+    <copy file="src/jvm/clojure/lang/package.html" tofile="target/tmpjd/package.html"/>
+    <replaceregexp file="target/tmpjd/IFn.java" match="(static public interface .*})" replace="" byline="true"/>
+    <javadoc destdir="target/javadoc"
+	    nodeprecatedlist="true" nohelp="true" nonavbar="true" notree="true"
+	    link="http://docs.oracle.com/javase/7/docs/api/"
+	    windowtitle="Clojure API">
+      <classpath>
+        <path location="${build}"/>
+      </classpath>
+      <fileset dir="${basedir}">
+	<include name="src/jvm/clojure/java/api/Clojure.java"/>
+	<include name="target/tmpjd/IFn.java"/>
+      </fileset>
+    </javadoc>
+  </target>
+
   <target name="all" depends="build,test,jar"/>
 
   <target name="clean"

diff --git a/src/jvm/clojure/api/API.java → src/jvm/clojure/java/api/Clojure.java b/src/jvm/clojure/api/API.java → src/jvm/clojure/java/api/Clojure.java
@@ -8,14 +8,47 @@
  *   You must not remove this notice, or any other, from this software.
  **/
 
-package clojure.api;
+package clojure.java.api;
 
 import clojure.lang.IFn;
 import clojure.lang.Symbol;
 import clojure.lang.Var;
 
-public class API {
-    private API() {}
+/**
+ * <p>The Clojure class provides a minimal interface to bootstrap Clojure access
+ * from other JVM languages. It provides:</p>
+ *
+ * <ol>
+ * <li>The ability to use Clojure's namespaces to locate an arbitrary
+ * <a href="http://clojure.org/vars">var</a>, returning the
+ * var's {@link clojure.lang.IFn} interface.</li>
+ * <li>A convenience method <code>read</code> for reading data using
+ * Clojure's edn reader</li>
+ * </ol>
+ *
+ * <p>To lookup and call a Clojure function:</p>
+ *
+ * <pre>
+ * IFn plus = Clojure.var("clojure.core", "+");
+ * plus.invoke(1, 2);</pre>
+ *
+ * <p>Functions in <code>clojure.core</code> are automatically loaded. Other
+ * namespaces can be loaded via <code>require</code>:</p>
+ *
+ * <pre>
+ * IFn require = Clojure.var("clojure.core", "require");
+ * require.invoke(Clojure.read("clojure.set"));</pre>
+ *
+ * <p><code>IFn</code>s can be passed to higher order functions, e.g. the
+ * example below passes <code>plus</code> to <code>read</code>:</p>
+ *
+ * <pre>
+ * IFn map = Clojure.var("clojure.core", "map");
+ * IFn inc = Clojure.var("clojure.core", "inc");
+ * map.invoke(inc, Clojure.read("[1 2 3]"));</pre>
+ */
+public class Clojure {
+    private Clojure() {}
 
     private static Symbol asSym(Object o) {
         Symbol s;
@@ -52,7 +85,7 @@ public static IFn var(Object ns, Object name) {
     /**
      * Read one object from the String s.  Reads data in the
      * <a href="http://edn-format.org">edn format</a>.
-     * @param     s
+     * @param s   a String
      * @return    an Object, or nil.
      */
     public static Object read(String s) {

diff --git a/src/jvm/clojure/api/package.html → src/jvm/clojure/java/api/package.html b/src/jvm/clojure/api/package.html → src/jvm/clojure/java/api/package.html
@@ -12,7 +12,7 @@
 
 <body>Clojure interop from Java.
 
-<p>The clojure.api package provides a minimal interface to bootstrap
+<p>The clojure.java.api package provides a minimal interface to bootstrap
   Clojure access from other JVM languages.  It does this by providing:
 </p>
 
@@ -25,7 +25,7 @@
 </ol>
 
 <p><code>IFn</code>s provide complete access to
-  Clojure's <a href="http://clojure.github.com/clojure/">API</a>s.
+  Clojure's <a href="http://clojure.github.io/clojure/">API</a>s.
   You can also access any other library written in Clojure, after adding
   either its source or compiled form to the classpath.</p>
 
@@ -34,7 +34,7 @@
 </p>
 
 <ol>
-<li>clojure.api.API</li>
+<li>clojure.java.api.Clojure</li>
 <li>clojure.lang.IFn</li>
 </ol>
 
@@ -43,25 +43,25 @@
 
 <p>To lookup and call a Clojure function:
 <pre>
-IFn plus = API.var("clojure.core", "+");
+IFn plus = Clojure.var("clojure.core", "+");
 plus.invoke(1, 2);
 </pre>
 </p>
 
 <p>Functions in <code>clojure.core</code> are automatically loaded. Other
   namespaces can be loaded via <code>require</code>:
 <pre>
-IFn require = API.var("clojure.core", "require");
-require.invoke(API.read("clojure.set"));
+IFn require = Clojure.var("clojure.core", "require");
+require.invoke(Clojure.read("clojure.set"));
 </pre>
 </p>
 
 <p><code>IFn</code>s can be passed to higher order functions, e.g. the
   example below passes <code>plus</code> to <code>read</code>:
 <pre>
-IFn map = API.var("clojure.core", "map");
-IFn inc = API.var("clojure.core", "inc");
-map.invoke(inc, API.read("[1 2 3]"));
+IFn map = Clojure.var("clojure.core", "map");
+IFn inc = Clojure.var("clojure.core", "inc");
+map.invoke(inc, Clojure.read("[1 2 3]"));
 </pre>
 </p>
 
@@ -70,8 +70,9 @@
   instead of <code>fn</code>:</p>
 
 <pre>
-IFn printLength = API.var("clojure.core", "*print-length*");
-API.var("clojure.core", "deref").invoke(printLength);
+IFn printLength = Clojure.var("clojure.core", "*print-length*");
+IFn deref = Clojure.var("clojure.core", "deref");
+deref.invoke(printLength);
 </pre>
 
 </body>

diff --git a/src/jvm/clojure/lang/IFn.java b/src/jvm/clojure/lang/IFn.java
@@ -14,6 +14,12 @@
 
 import java.util.concurrent.Callable;
 
+/**
+ * <p><code>IFn</code> provides complete access to invoking
+ * any of Clojure's <a href="http://clojure.github.io/clojure/">API</a>s.
+ * You can also access any other library written in Clojure, after adding
+ * either its source or compiled form to the classpath.</p>
+ */
 public interface IFn extends Callable, Runnable{
 
 public Object invoke() ;

diff --git a/src/jvm/clojure/lang/package.html b/src/jvm/clojure/lang/package.html
@@ -0,0 +1,21 @@
+<html>
+
+<!--
+Copyright (c) Rich Hickey and Contributors. All rights reserved.
+The use and distribution terms for this software are covered by the
+Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
+which can be found in the file epl-v10.html at the root of this distribution.
+By using this software in any fashion, you are agreeing to be bound by
+the terms of this license.
+You must not remove this notice, or any other, from this software.
+-->
+
+<body>Clojure language implementation.
+
+<p>The clojure.lang package holds the implementation for Clojure.
+The only class considered part of the public API is
+{@link clojure.lang.IFn}. All other classes should be considered
+implementation details.</p>
+
+</body>
+</html>
diff --git a/test/clojure/test_clojure/api.clj b/test/clojure/test_clojure/api.clj
@@ -10,45 +10,45 @@
   (:require [clojure.test.generative :refer (defspec)]
             [clojure.test-clojure.generators :as cgen])
   (:import clojure.lang.IFn
-           clojure.api.API
+           clojure.java.api.Clojure
            clojure.lang.Var))
 
 (set! *warn-on-reflection* true)
 
 (defn roundtrip
-  "Print an object and read it back with API/read"
+  "Print an object and read it back with Clojure/read"
   [o]
   (binding [*print-length* nil
             *print-dup* nil
             *print-level* nil]
-    (API/read (pr-str o))))
+    (Clojure/read (pr-str o))))
 
 (defn api-var-str
   [^Var v]
-  (API/var (str (.name (.ns v)))
-           (str (.sym v))))
+  (Clojure/var (str (.name (.ns v)))
+               (str (.sym v))))
 
 (defn api-var
   [^Var v]
-  (API/var (.name (.ns v))
-           (.sym v)))
+  (Clojure/var (.name (.ns v))
+               (.sym v)))
 
 (defspec api-can-read
   roundtrip
   [^{:tag cgen/ednable} o]
   (when-not (= o %)
-    (throw (ex-info "Value cannot roundtrip with API/read" {:printed o :read %}))))
+    (throw (ex-info "Value cannot roundtrip with Clojure/read" {:printed o :read %}))))
 
 (defspec api-can-find-var
   api-var
   [^{:tag cgen/var} v]
   (when-not (= v %)
-    (throw (ex-info "Var cannot roundtrip through API/var" {:from v :to %}))))
+    (throw (ex-info "Var cannot roundtrip through Clojure/var" {:from v :to %}))))
 
 (defspec api-can-find-var-str
   api-var-str
   [^{:tag cgen/var} v]
   (when-not (= v %)
-    (throw (ex-info "Var cannot roundtrip strings through API/var" {:from v :to %}))))
+    (throw (ex-info "Var cannot roundtrip strings through Clojure/var" {:from v :to %}))))