Merge branch 'master' into more_marginalia

Conflicts:
	src/marginalia/core.clj
	src/marginalia/html.clj

Merged by accepting changes to definition and usage of
  html/uberdoc-html

README.md

@@ -13,15 +13,15 @@ Currently Marginalia can be used in a number of ways as described below.
 
 ### Command Line
 
-You can download the [Marginalia 0.3.2 jar including packaged dependencies from Github](https://github.com/downloads/fogus/marginalia/marginalia-0.3.2-standalone.jar).
+You can download the [Marginalia 0.5.0 jar including packaged dependencies from Github](https://github.com/downloads/fogus/marginalia/marginalia-0.5.0-standalone.jar).
 
 Running Marginalia given the jar file linked above is as easy as:
 
-    java -jar marginalia-0.3.2-standalone.jar
+    java -jar marginalia-0.5.0-standalone.jar
 
 This will search the `PWD` for a `src` directory which it will then traverse looking for Clojure source files to parse and generate documentation for.  Marginalia also takes specific locations and files to generate docs for:
 
-    java -jar marginalia-0.3.2-standalone.jar <file1> <file2> ... <filen>
+    java -jar marginalia-0.5.0-standalone.jar <file1> <file2> ... <filen>
 
 Arguments can be specific files or directories.
 
@@ -29,7 +29,7 @@ Arguments can be specific files or directories.
 
 To use Marginalia in your own projects simply add the following to your `project.clj` file in the `:dev-dependencies` section:
 
-    [marginalia "0.3.2"]
+    [marginalia "0.5.0"]
 
 After executing `lein deps` you can generate your complete source documentation with the following command:
 

project.clj

@@ -1,4 +1,4 @@
-(defproject marginalia "0.5.0-alpha"
+(defproject marginalia "0.5.0"
   :description "lightweight literate programming for clojure -- inspired by [docco](http://jashkenas.github.com/docco/)"
   :main marginalia.core
   :eval-in-leiningen true

resources/shBrushClojure.js

@@ -164,7 +164,7 @@ SyntaxHighlighter.brushes.Clojure = function () {
 		{ regex: /\b(true|false|nil)\b/g,
 			css: 'value' },
 		// (un)quoted symbols
-		{ regex: /(`|#?'|~@?)[\w-.\/]+/g,
+		{ regex: /(`|#?'|~@?)[\w-.A-Za-z0-9_<>\-]+/g,
 			css: 'color1' },
 		// keywords
 		{ regex: /:[A-Za-z0-9_\-]+/g,
@@ -177,7 +177,8 @@ SyntaxHighlighter.brushes.Clojure = function () {
 			css: 'preprocessor' },
 		// clojure.core
 		{ regex: new ClojureRegExp(this.getKeywords(clojure_core)),
-			css: 'functions' }
+			css: 'functions' },
+                { regex: /[A-Za-z0-9_<>\-]+/g,  css: 'plain'}
 	];
 
 	this.forHtmlScript(SyntaxHighlighter.regexLib.scriptScriptTags);

src/leiningen/marg.clj

@@ -5,7 +5,8 @@
 
 (defn marg [project & args]
   (eval-in-project project
-    `(marginalia.core/run-marginalia (list ~@args))
+    `(binding [marginalia.html/*resources* ""]
+       (marginalia.core/run-marginalia (list ~@args)))
     nil
     nil
     '(require 'marginalia.core)))

src/marginalia/core.clj

@@ -179,9 +179,9 @@
   "
   [output-file-name files-to-analyze props]
   (let [source (uberdoc-html
-                output-file-name
-                (map path-to-doc files-to-analyze)
-                props)))
+                props
+                (map path-to-doc files-to-analyze))]
+    (spit output-file-name source)))
 
 ;; ## External Interface (command-line, lein, cake, etc)
 

src/marginalia/html.clj

@@ -26,10 +26,22 @@
 (defn slurp-resource
   "Stolen from leiningen"
   [resource-name]
-  (-> (.getContextClassLoader (Thread/currentThread))
-      (.getResourceAsStream resource-name)
-      (java.io.InputStreamReader.)
-      (slurp)))
+  (try 
+    (-> (.getContextClassLoader (Thread/currentThread))
+        (.getResourceAsStream resource-name)
+        (java.io.InputStreamReader.)
+        (slurp))
+    (catch java.lang.NullPointerException npe
+      (println (str "Could not locate resources at " resource-name))
+      (println "    ... attempting to fix.")
+      (let [resource-name (str "./resources/" resource-name)]
+        (try
+          (-> (.getContextClassLoader (Thread/currentThread))
+              (.getResourceAsStream resource-name)
+              (java.io.InputStreamReader.)
+              (slurp))
+          (catch java.lang.NullPointerException npe
+            (println (str "    STILL could not locate resources at " resource-name ". Giving up!"))))))))
 
 (defn inline-js [resource]
   (let [src (slurp-resource resource)]
@@ -183,7 +195,7 @@
      [:br]
      [:br]
      [:br]
-     "(this space intentionally left blank)"]]))
+     "(this space intentionally left almost blank)"]]))
 
 (defn toc-html [docs]
   (html
@@ -352,11 +364,6 @@
     [:head
      [:meta {:http-equiv "Content-Type" :content "text/html" :charset "utf-8"}]
      [:meta {:name "description" :content (:description project-metadata)}]
-     (inline-js (str *resources* "jquery-1.4.4.min.js"))
-     (inline-js (str *resources* "xregexp-min.js"))
-     (inline-js (str *resources* "shCore.js"))
-     (inline-js (str *resources* "shBrushClojure.js"))
-     (inline-js (str *resources* "app.js"))
      #_[:script {:type "text/javascript" :src "./../resources/app.js"}]
      (inline-css (str *resources* "shCore.css"))
      (css
@@ -366,6 +373,11 @@
      header-css
      floating-toc-css
      general-css
+     (inline-js (str *resources* "jquery-1.4.4.min.js"))
+     (inline-js (str *resources* "xregexp-min.js"))
+     (inline-js (str *resources* "shCore.js"))
+     (inline-js (str *resources* "shBrushClojure.js"))
+     (inline-js (str *resources* "app.js"))
      opt-resources
      [:title (:name project-metadata) " -- Marginalia"]]
     [:body
@@ -393,7 +405,7 @@
 (defn uberdoc-html
   "This generates a stand alone html file (think `lein uberjar`).
    It's probably the only var consumers will use."
-  [output-file-name docs project-metadata ]
+  [project-metadata docs]
   (page-template
    project-metadata
    (opt-resources-html project-metadata)

src/marginalia/parser.clj

@@ -79,6 +79,19 @@
       (replace #"\n\s*\n" "\n")
       (replace #"\n\s*\)" ")")))
 
+(defn- internal-strip-docstring
+  [R internal-ds]
+  (reduce (fn [raw docstring]
+            (replace
+             raw
+             (str \" (-> docstring
+                         str
+                         (replace "\"" "\\\""))
+                  \")
+             ""))
+          R
+          internal-ds))
+
 (defn get-var-docstring [nspace-sym sym]
   (try
     (-> `(var ~(symbol (str nspace-sym) (str sym))) eval meta :doc)
@@ -101,6 +114,25 @@
        (strip-docstring docstring raw)
        (if nspace sym nspace-sym)])))
 
+(defn- extract-impl-docstring
+  [fn-body]
+  (filter string? (rest fn-body)))
+
+(defn- extract-internal-docstrings 
+  [body]
+  (mapcat #(extract-impl-docstring %)
+          body))
+
+(defmethod dispatch-form 'defprotocol
+  [form raw nspace-sym]
+  (let [[ds r s] (extract-common-docstring form raw nspace-sym)]
+    (let [internal-dses (if ds
+                          (extract-internal-docstrings (nthnext form 3))
+                          (extract-internal-docstrings (nthnext form 2)))]
+      (with-meta
+        [ds r s]
+        {:internal-docstrings internal-dses}))))
+
 (defmethod dispatch-form 'ns
   [form raw nspace-sym]
   (let [[ds r s] (extract-common-docstring form raw nspace-sym)]
@@ -118,9 +150,8 @@
   [form raw nspace-sym]
   (extract-common-docstring form raw nspace-sym))
 
-(defmethod dispatch-form 'defprotocol
+(defmethod dispatch-form 'defn-
   [form raw nspace-sym]
-  ;; this needs some work to extract embedded docstrings
   (extract-common-docstring form raw nspace-sym))
 
 (defmethod dispatch-form 'defmulti

src/problem_cases/general.clj

@@ -22,6 +22,7 @@
   (* x x))
 
 (defprotocol Relation
+  "Defines a relation... duh!"
   (select     [this predicate]
     "Confines the query to rows for which the predicate is true
 
@@ -86,3 +87,63 @@
   "This is a docstring.  On the left."
   [_]
   "GENERATED ALWAYS AS IDENTITY")
+
+(defn strict-eval-op-fn
+  "`strict-eval-op-fn` is used to define functions of the above pattern for fuctions such as `+`, `*`,   etc.  Cljs special forms defined this way are applyable, such as `(apply + [1 2 3])`.
+
+   Resulting expressions are wrapped in an anonymous function and, down the line, `call`ed, like so:
+
+       (+ 1 2 3) -> (function(){...}.call(this, 1 2 3)"
+  [op inc-ind-str ind-str op nl]
+  (ind-str
+   "(function() {" nl
+   (inc-ind-str
+    "var _out = arguments[0];" nl
+    "for(var _i=1; _i<arguments.length; _i++) {" nl
+    (inc-ind-str
+     "_out = _out " op " arguments[_i];")
+    nl
+    "}" nl
+    "return _out;")
+   nl
+   "})"))
+
+
+'(defn special-forms []
+  {'def     handle-def
+   'fn      handle-fn
+   'fn*     handle-fn
+   'set!    handle-set
+   'let     handle-let
+   'defn    handle-defn
+   'aget    handle-aget
+   'aset    handle-aset
+   'if      handle-if
+   'while   handle-while
+   'when    handle-when
+   'doto    handle-doto
+   '->      handle-->
+   '->>     handle-->>
+   'not     handle-not
+   'do      handle-do
+   'cond    handle-cond
+   '=       (make-lazy-op '==)
+   '>       (make-lazy-op '>)
+   '<       (make-lazy-op '<)
+   '>=      (make-lazy-op '>=)
+   '<=      (make-lazy-op '<=)
+   'or      (make-lazy-op '||)
+   'and     (make-lazy-op '&&)
+   'doseq   handle-doseq
+   'instanceof handle-instanceof
+   'gensym handle-gensym
+   'gensym-str handle-gensym-str})
+
+'(defn greater [a b]
+  (>= a b))
+
+'(fact
+  (greater 2 1) => truthy)
+
+'(file->tickets commits)
+