Browse files

Polish the documentation some more.

  • Loading branch information...
1 parent 192bdaf commit 7d617854799148a3755da11948b99d1c0a0fa112 @jafingerhut committed Dec 3, 2011
Showing with 87 additions and 34 deletions.
  1. +87 −34 src/cd_client/core.clj
View
121 src/cd_client/core.clj
@@ -35,9 +35,32 @@
(def ^:private ^:dynamic *cd-client-mode* (ref {:source :web}))
-(defn set-local-mode! [fname]
- ;; Handle errors in attempting to open the file, or as returned from
- ;; read?
+;; Handle errors in attempting to open the file, or as returned from
+;; read?
+
+(defn set-local-mode!
+ "Change the behavior of future calls to cdoc and other documentation
+ access functions and macros in cd-client.core. Instead of using the
+ Internet, their results will be obtained from a file. This can be
+ useful when you do not have Internet access. Even if you do have
+ access, you may be able to get results more quickly in local mode,
+ and you will not put load on the clojuredocs.org servers.
+
+ Use set-web-mode! if you wish to change the mode back to retrieving
+ results from the Internet, or show-mode to see which mode you are
+ in.
+
+ A snapshot file is available here:
+
+ http://github.com/jafingerhut/cd-client/TBD
+
+ Example:
+
+ user=> (set-local-mode! \"clojuredocs-snapshot-2011-12-03.txt\")
+ Read info on 3574 names from file: clojuredocs-snapshot-2011-12-03.txt
+ Snapshot time: Sat Dec 03 18:03:43 PST 2011
+ nil"
+ [fname]
(let [x (with-open [s (java.io.PushbackReader.
(java.io.InputStreamReader.
(java.io.FileInputStream.
@@ -53,12 +76,24 @@
(println "Snapshot time:" snapshot-time)))
-(defn set-web-mode! []
+(defn set-web-mode!
+ "Change the behavior of future calls to cdoc and other documentation
+ access functions and macros in cd-client.core. Their results will
+ be obtained by accessing clojuredocs.org over the Internet.
+
+ See also: set-local-mode! show-mode"
+ []
(dosync (alter *cd-client-mode* (fn [cur-val] {:source :web})))
(println "Now retrieving clojuredocs data from web site" *clojuredocs-root*))
-(defn show-mode []
+(defn show-mode
+ "Print the mode you are in, local or web, for accessing
+ documentation with cdoc and other macros and functions in
+ cd-client.core.
+
+ See also: set-local-mode! set-web-mode!"
+ []
(let [mode @*cd-client-mode*]
(if (= :web (:source mode))
(println "Web mode. Data is retrieved from" *clojuredocs-root*)
@@ -173,7 +208,7 @@
(defmacro examples
- "Return examples from clojuredocs for a given (unquoted) var, fn, macro,
+ "Return examples from clojuredocs for a given unquoted var, fn, macro,
special form, or a namespace and name (as strings). Returns a map
with a structure defined by the clojuredocs.org API.
@@ -195,8 +230,8 @@
;; saying that cd-client.core/pr-examples-core is not public.
(defn pr-examples-core
- "Given a namespace and name (as strings), pretty-print all the examples for it
- from clojuredocs."
+ "Given a namespace and name (as strings), pretty-print all the
+ examples for it from clojuredocs."
[ns name & verbose]
(let [res (examples-core ns name)
n (count (:examples res))]
@@ -219,8 +254,8 @@
(defmacro pr-examples
- "Given an (unquoted) var, fn, macro, special form, or a namespace
- and name (as strings), pretty-print all the examples for it from
+ "Given an unquoted var, fn, macro, special form, or a namespace and
+ name (as strings), pretty-print all the examples for it from
clojuredocs.
See cdoc documentation for examples of the kinds of arguments that
@@ -234,13 +269,17 @@
;; TBD: Think about how to implement search when in local mode.
(defn search
- "Search for a method name within an (optional) namespace"
+ "Search for a method name within an (optional) namespace.
+
+ Note: This currently always attempts to access clojuredocs, even if
+ you have used set-local-mode!"
([name] (get-simple (str *search-api* name)))
([ns name] (get-simple (str *search-api* ns "/" name))))
(defn comments-core
- "Return comments from clojuredocs for a given namespace and name (as strings)"
+ "Return comments from clojuredocs for a given namespace and name (as
+ strings)"
[ns name]
(let [mode @*cd-client-mode*]
(if (= :web (:source mode))
@@ -250,7 +289,7 @@
(defmacro comments
- "Return comments from clojuredocs for a given (unquoted) var, fn, macro,
+ "Return comments from clojuredocs for a given unquoted var, fn, macro,
special form, or namespace and name (as strings). Returns nil if
there are no comments, or a vector of maps with a structure defined
by the clojuredocs.org API if there are comments.
@@ -289,7 +328,7 @@
(defmacro pr-comments
- "Given a (unquoted) var, fn, macro, special form, or a namespace and
+ "Given an unquoted var, fn, macro, special form, or a namespace and
name (as strings), pretty-print all the comments for it from
clojuredocs.
@@ -302,7 +341,8 @@
(defn see-also-core
- "Return 'see also' info from clojuredocs for a given namespace and name (as strings)"
+ "Return 'see also' info from clojuredocs for a given namespace and
+ name (as strings)"
[ns name]
(let [mode @*cd-client-mode*]
(if (= :web (:source mode))
@@ -312,7 +352,7 @@
(defmacro see-also
- "Given a (unquoted) var, fn, macro, special form, or a namespace and
+ "Given an unquoted var, fn, macro, special form, or a namespace and
name (as strings), show the 'see also' for it from clojuredocs.
Returns nil if there are no 'see alsos', or a vector of maps with a
structure defined by the clojuredocs.org API if there are comments.
@@ -344,7 +384,7 @@
(defmacro pr-see-also
- "Given a (unquoted) var, fn, macro, special form, or a namespace and
+ "Given an unquoted var, fn, macro, special form, or a namespace and
name (as strings), pretty-print the 'see also' for it from
clojuredocs.
@@ -366,28 +406,34 @@
(defmacro cdoc
- "Given a (unquoted) var, fn, macro, special form, or a namespace and
+ "Given an unquoted var, fn, macro, special form, or a namespace and
name (as strings), show the Clojure documentation, and any examples,
see also pointers, and comments available on clojuredocs.
+ By default, cdoc and its related functions and macros in
+ cd-client.core use the Internet to access clojuredocs.org at the
+ time you invoke them. If you wish to work off line from a snapshot
+ file, use set-local-mode!
+
+ See also: set-local-mode! pr-examples browse-to
+
Examples:
(cdoc *)
(cdoc catch)
(cdoc ->>)
Just as for clojure.repl/doc, you may name a var, fn, or macro using
- the full namespace/name, or any shorter version that you can use
- given additions to the current namespace from prior calls to
- require, use, refer, etc.
+ the full namespace/name, or any shorter version accessible due to
+ prior calls to require, use, refer, etc.
- Thus the two cdoc invocations below give the same result:
+ Thus the two cdoc calls below give the same result:
(cdoc clojure.string/join)
(require '[clojure.string :as str])
(cdoc str/join)
- And all of the below give the same result:
+ And all of the cdoc calls below give the same result:
(cdoc \"clojure.java.io\" \"reader\")
(cdoc clojure.java.io/reader)
@@ -412,10 +458,14 @@
(defmacro browse-to
- "Given a (unquoted) var, fn, macro, or special form, or a namespace
+ "Given an unquoted var, fn, macro, or special form, or a namespace
and name (as strings), open a browser to the clojuredocs page for
it.
+ Note: This macro always attempts to access the Internet, even if you
+ have used set-local-mode! Clojuredocs web page contents are not
+ saved in a snapshot file at this time.
+
See cdoc documentation for examples of the kinds of arguments that
can be given. This macro can be given the same arguments as cdoc."
([name]
@@ -428,17 +478,20 @@
;; + examples, see also list, and comments
;; + DON'T get the Clojure documentation string. Assume we have that
;; locally already.
-;;
-;; Use search-str "let" to get a partial snapshot, with only those
-;; names that contain "let". This currently returns 39 results, so it
-;; is a nice smaller test case for development and debugging.
-;;
-;; Use search-str "" to get a full snapshot. As of Mar 3, 2011 that
-;; is information on a little over 4000 names, requiring 3 API calls
-;; per name. Best to ask permission before hitting the server with
-;; this kind of use.
-(defn make-snapshot [search-str fname & quiet]
+(defn make-snapshot
+ "Create a snapshot file that can be read in with set-local-mode!
+
+ Warning: Please consider using a snapshot file created by someone
+ else, since doing so using this function can take a long time (over
+ an hour), and if many people do so it could add significant load to
+ the clojuredocs server.
+
+ Examples:
+
+ (make-snapshot \"\" \"clojuredocs-snapshot-2011-12-03.txt\")
+ (make-snapshot \"let\" \"only-clojuredocs-symbols-containing-let.txt\")"
+ [search-str fname & quiet]
(let [verbose (not quiet)
all-names-urls (search search-str)
junk (when verbose

0 comments on commit 7d61785

Please sign in to comment.