tweaking what gets exposed (javadoc #357)

Signed-off-by: Stuart Halloway <stu@thinkrelevance.com>

10 files changed, 96 insertions, 46 deletions

diff --git a/build.xml b/build.xml
index d4f2ab0a..0d88a3b5 100644
--- a/build.xml
+++ b/build.xml
@@ -107,6 +107,10 @@
       <arg value="clojure.pprint"/>
       <arg value="clojure.java.io"/>
       <arg value="clojure.repl"/>
+      <arg value="clojure.java.browse"/>
+      <arg value="clojure.java.javadoc"/>
+      <arg value="clojure.java.shell"/>
+      <arg value="clojure.java.browse-ui"/>
     </java>
   </target>
 
diff --git a/src/clj/clojure/java/browse.clj b/src/clj/clojure/java/browse.clj
index a65b4bcd..f4466f5c 100644
--- a/src/clj/clojure/java/browse.clj
+++ b/src/clj/clojure/java/browse.clj
@@ -7,8 +7,8 @@
 ;   You must not remove this notice, or any other, from this software.
 
 (ns 
-  #^{:author "Christophe Grand",
-     :doc "Start a web browser from Clojure"}
+  ^{:author "Christophe Grand",
+    :doc "Start a web browser from Clojure"}
   clojure.java.browse
   (:require [clojure.java.shell :as sh]) 
   (:import (java.net URI)))
@@ -43,7 +43,10 @@
   (require 'clojure.contrib.javadoc.browse-ui)
   ((find-var 'clojure.contrib.javadoc.browse-ui/open-url-in-swing) url))
 
-(defn browse-url [url]
+(defn browse-url
+  "Open url in a browser"
+  {:added "1.2"}
+  [url]
   (or (open-url-in-browser url)
       (when *open-url-script* (sh/sh *open-url-script* (str url)) true)
       (open-url-in-swing url)))
diff --git a/src/clj/clojure/java/browse_ui.clj b/src/clj/clojure/java/browse_ui.clj
index a0d15a3a..e2c858d2 100644
--- a/src/clj/clojure/java/browse_ui.clj
+++ b/src/clj/clojure/java/browse_ui.clj
@@ -7,13 +7,12 @@
 ;   You must not remove this notice, or any other, from this software.
 
 (ns
-    #^{:author "Christophe Grand",
-       :doc "Helper namespace for clojure.java.browse.
-             Prevents console apps from becoming GUI unnecessarily."}
+    ^{:author "Christophe Grand",
+      :doc "Helper namespace for clojure.java.browse.
+            Prevents console apps from becoming GUI unnecessarily."}
   clojure.java.browse-ui)
 
-(defn open-url-in-swing
-  "Opens url (a string) in a Swing window."
+(defn- open-url-in-swing
   [url]
   (let [htmlpane (javax.swing.JEditorPane. url)]
     (.setEditable htmlpane false)
diff --git a/src/clj/clojure/java/javadoc.clj b/src/clj/clojure/java/javadoc.clj
index e64ecf1a..cefdff1f 100644
--- a/src/clj/clojure/java/javadoc.clj
+++ b/src/clj/clojure/java/javadoc.clj
@@ -16,19 +16,14 @@
 (def *feeling-lucky-url* "http://www.google.com/search?btnI=I%27m%20Feeling%20Lucky&q=allinurl:")
 (def *feeling-lucky* true)
 
-(def
-    #^{:doc "Ref to a list of local paths for Javadoc-generated HTML files."}
- *local-javadocs* (ref (list)))
+(def *local-javadocs* (ref (list)))
  
 (def *core-java-api*
   (if (= "1.5" (System/getProperty "java.specification.version"))
     "http://java.sun.com/j2se/1.5.0/docs/api/"
     "http://java.sun.com/javase/6/docs/api/"))
 
-(def
- #^{:doc "Ref to a map from package name prefixes to URLs for remote
-  Javadocs."}
- *remote-javadocs*
+(def *remote-javadocs*
  (ref (sorted-map
        "java." *core-java-api*
        "javax." *core-java-api*
@@ -42,24 +37,27 @@
 
 (defn add-local-javadoc
   "Adds to the list of local Javadoc paths."
+  {:added "1.2"}
   [path]
   (dosync (commute *local-javadocs* conj path)))
 
 (defn add-remote-javadoc
   "Adds to the list of remote Javadoc URLs.  package-prefix is the
   beginning of the package name that has docs at this URL."
+  {:added "1.2"}
   [package-prefix url]
   (dosync (commute *remote-javadocs* assoc package-prefix url)))
 
-(defn- find-javadoc-url
+(defn- javadoc-url
   "Searches for a URL for the given class name.  Tries
   *local-javadocs* first, then *remote-javadocs*.  Returns a string."
-  {:tag String}
-  [#^String classname]
+  {:tag String,
+   :added "1.2"}
+  [^String classname]
   (let [file-path (.replace classname \. File/separatorChar)
         url-path (.replace classname \. \/)]
-    (if-let [file #^File (first
-                           (filter #(.exists #^File %)
+    (if-let [file ^File (first
+                           (filter #(.exists ^File %)
                              (map #(File. (str %) (str file-path ".html"))
                                @*local-javadocs*)))]
       (-> file .toURI str)
@@ -74,10 +72,11 @@
 (defn javadoc
   "Opens a browser window displaying the javadoc for the argument.
   Tries *local-javadocs* first, then *remote-javadocs*."
+  {:added "1.2"}
   [class-or-object]
-  (let [#^Class c (if (instance? Class class-or-object) 
+  (let [^Class c (if (instance? Class class-or-object) 
                     class-or-object 
                     (class class-or-object))]
-    (if-let [url (find-javadoc-url (.getName c))]
+    (if-let [url (javadoc-url (.getName c))]
       (browse-url url)
       (println "Could not find Javadoc for" c))))
diff --git a/src/clj/clojure/java/shell.clj b/src/clj/clojure/java/shell.clj
index ae96797f..e8a8427b 100644
--- a/src/clj/clojure/java/shell.clj
+++ b/src/clj/clojure/java/shell.clj
@@ -7,8 +7,8 @@
 ;   You must not remove this notice, or any other, from this software.
 
 (ns 
-  #^{:author "Chris Houser, Stuart Halloway",
-     :doc "Conveniently launch a sub-process providing its stdin and
+  ^{:author "Chris Houser, Stuart Halloway",
+    :doc "Conveniently launch a sub-process providing its stdin and
 collecting its stdout"}
   clojure.java.shell
   (:use [clojure.java.io :only (as-file)])
@@ -17,13 +17,17 @@ collecting its stdout"}
 (def *sh-dir* nil)
 (def *sh-env* nil)
 
-(defmacro with-sh-dir [dir & forms]
+(defmacro with-sh-dir
   "Sets the directory for use with sh, see sh for details."
+  {:added "1.2"}
+  [dir & forms]
   `(binding [*sh-dir* ~dir]
      ~@forms))
 
-(defmacro with-sh-env [env & forms]
+(defmacro with-sh-env
   "Sets the environment for use with sh, see sh for details."
+  {:added "1.2"}
+  [env & forms]
   `(binding [*sh-env* ~env]
      ~@forms))
      
@@ -43,26 +47,23 @@ collecting its stdout"}
     target))
 
 (defn- parse-args
-  "Takes a seq of 'sh' arguments and returns a map of option keywords
-  to option values."
   [args]
-  (loop [[arg :as args] args opts {:cmd [] :out "UTF-8" :dir *sh-dir* :env *sh-env*}]
-    (if-not args
-      opts
-      (if (keyword? arg)
-        (recur (nnext args) (assoc opts arg (second args)))
-        (recur (next args) (update-in opts [:cmd] conj arg))))))
-
-(defn- as-env-key [arg]
+  (let [default-opts {:out "UTF-8" :dir *sh-dir* :env *sh-env*}
+        [cmd opts] (split-with string? args)]
+    [cmd (merge default-opts (apply hash-map opts))]))
+
+(defn- as-env-key 
   "Helper so that callers can use symbols, keywords, or strings
    when building an environment map."
+  [arg]
   (cond
    (symbol? arg) (name arg)
    (keyword? arg) (name arg)
    (string? arg) arg))
 
-(defn- as-env-string [arg]
-  "Helper so that callers can pass a Clojure map for the :env to sh." 
+(defn- as-env-string 
+  "Helper so that callers can pass a Clojure map for the :env to sh."
+  [arg]
   (cond
    (nil? arg) nil
    (map? arg) (into-array String (map (fn [[k v]] (str (as-env-key k) "=" v)) arg))
@@ -92,12 +93,14 @@ collecting its stdout"}
     :exit => sub-process's exit code
     :out  => sub-process's stdout (as byte[] or String)
     :err  => sub-process's stderr (as byte[] or String)"
+  {:added "1.2"}
   [& args]
-  (let [opts (parse-args args)
+  (let [[cmd opts] (parse-args args)
         proc (.exec (Runtime/getRuntime) 
-		    (into-array (:cmd opts)) 
+		    (into-array cmd) 
 		    (as-env-string (:env opts))
 		    (as-file (:dir opts)))]
+    (println opts)
     (if (:in opts)
       (with-open [osw (OutputStreamWriter. (.getOutputStream proc))]
         (.write osw (:in opts)))
diff --git a/src/clj/clojure/main.clj b/src/clj/clojure/main.clj
index 19aea435..31cdd957 100644
--- a/src/clj/clojure/main.clj
+++ b/src/clj/clojure/main.clj
@@ -194,7 +194,8 @@
       (catch Throwable e
         (caught e)
         (set! *e e)))
-     (use '[clojure.repl :only (source-fn source apropos dir-fn dir)])
+     (use '[clojure.repl :only (source apropos dir)])
+     (use '[clojure.java.javadoc :only (javadoc)])
      (prompt)
      (flush)
      (loop []
diff --git a/test/clojure/test_clojure/java/io.clj b/test/clojure/test_clojure/java/io.clj
index d193942d..2b831b72 100644
--- a/test/clojure/test_clojure/java/io.clj
+++ b/test/clojure/test_clojure/java/io.clj
@@ -1,3 +1,11 @@
+;   Copyright (c) Rich Hickey. 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.
+
 (ns clojure.test-clojure.java.io
   (:use clojure.test clojure.java.io)
   (:import (java.io File FileInputStream BufferedInputStream
diff --git a/test/clojure/test_clojure/java/javadoc.clj b/test/clojure/test_clojure/java/javadoc.clj
new file mode 100644
index 00000000..575314cf
--- /dev/null
+++ b/test/clojure/test_clojure/java/javadoc.clj
@@ -0,0 +1,22 @@
+;   Copyright (c) Rich Hickey. 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.
+
+(ns clojure.test-clojure.java.javadoc
+  (:use clojure.test
+	[clojure.java.javadoc :as j])
+  (:import (java.io File)))
+
+(deftest javadoc-url-test
+  (testing "for a core api"
+    (binding [*feeling-lucky* false]
+      (are [x y] (= x (#'j/javadoc-url y))
+           nil "foo.Bar"
+           (str *core-java-api* "java/lang/String.html") "java.lang.String")))
+  (testing "for a remote javadoc"
+    (binding [*remote-javadocs* (ref (sorted-map "java." "http://example.com/"))]
+      (is (= "http://example.com/java/lang/Number.html" (#'j/javadoc-url "java.lang.Number"))))))
diff --git a/test/clojure/test_clojure/java/shell.clj b/test/clojure/test_clojure/java/shell.clj
index a8c6f0a0..777698e2 100644
--- a/test/clojure/test_clojure/java/shell.clj
+++ b/test/clojure/test_clojure/java/shell.clj
@@ -1,3 +1,11 @@
+;   Copyright (c) Rich Hickey. 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.
+
 (ns clojure.test-clojure.java.shell
   (:use clojure.test
 	[clojure.java.shell :as sh])
@@ -5,10 +13,10 @@
 
 (deftest test-parse-args
   (are [x y] (= x y)
-    {:cmd [nil] :out "UTF-8" :dir nil :env nil} (#'sh/parse-args [])
-    {:cmd ["ls"] :out "UTF-8" :dir nil :env nil} (#'sh/parse-args ["ls"])
-    {:cmd ["ls" "-l"] :out "UTF-8" :dir nil :env nil} (#'sh/parse-args ["ls" "-l"])
-    {:cmd ["ls"] :out "ISO-8859-1" :dir nil :env nil} (#'sh/parse-args ["ls" :out "ISO-8859-1"])))
+       [[] {:out "UTF-8" :dir nil :env nil}] (#'sh/parse-args [])
+       [["ls"] {:out "UTF-8" :dir nil :env nil}] (#'sh/parse-args ["ls"])
+       [["ls" "-l"] {:out "UTF-8" :dir nil :env nil}] (#'sh/parse-args ["ls" "-l"])
+       [["ls"] {:out "ISO-8859-1" :dir nil :env nil}] (#'sh/parse-args ["ls" :out "ISO-8859-1"])))
   
 (deftest test-with-sh-dir
   (are [x y] (= x y)
diff --git a/test/clojure/test_clojure/metadata.clj b/test/clojure/test_clojure/metadata.clj
index 53919e9d..ce93912a 100644
--- a/test/clojure/test_clojure/metadata.clj
+++ b/test/clojure/test_clojure/metadata.clj
@@ -21,7 +21,10 @@
     clojure.walk
     clojure.xml
     clojure.zip
-    clojure.java.io])
+    clojure.java.io
+    clojure.java.browse
+    clojure.java.javadoc
+    clojure.java.shell])
 
 (doseq [ns public-namespaces]
   (require ns))