yogsototh/marginalia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Added support for defmacro, defmulti, and defmethod. bumped version number

Browse source
This commit is contained in:
fogus 2011-01-05 13:20:04 -05:00
parent f10fa0456d
commit 6370828480
7 changed files with 78 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -16,15 +16,15 @@ Currently Marginalia can be used in a number of ways as described below.
### Command Line
You can download the [Marginalia 0.2.4 jar including packaged dependencies from Github](https://github.com/downloads/fogus/marginalia/marginalia-0.2.4-standalone.jar).
You can download the [Marginalia 0.3.0 jar including packaged dependencies from Github](https://github.com/downloads/fogus/marginalia/marginalia-0.3.0-standalone.jar).
Running Marginalia given the jar file linked above is as easy as:
java -jar marginalia-0.2.4-standalone.jar
java -jar marginalia-0.3.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.2.4-standalone.jar <file1> <file2> ... <filen>
java -jar marginalia-0.3.0-standalone.jar <file1> <file2> ... <filen>
Arguments can be specific files or directories.
@ -32,7 +32,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.2.4"]
[marginalia "0.3.0"]
After executing `lein deps` you can generate your complete source documentation with the following command:

4
project.clj
View file

@ -1,4 +1,4 @@
(defproject marginalia "0.2.4"
(defproject marginalia "0.3.0"
:description "lightweight literate programming for clojure -- inspired by [docco](http://jashkenas.github.com/docco/)"
:main marginalia.core
:dependencies
@ -12,7 +12,7 @@
;;Needed for testing lein plugin
[hiccup "0.3.0"]
[org.clojars.nakkaya/markdownj "1.0.2b4"]
[marginalia "0.2.4"]]
[marginalia "0.3.0"]]
;;Needed for testing cake plugin
:tasks [marginalia.tasks]
;;Needed for testing Latex equation formatting. You must download

54
site/src/uberdoc.html
View file

@ -1,5 +1,5 @@
<!DOCTYPE html>
<html><head><script type="text/javascript">/*!
<html><head><meta charset="utf-8" content="text/html" http-equiv="Content-Type" /><script type="text/javascript">/*!
* jQuery JavaScript Library v1.4.4
* http://jquery.com/
*
@ -2525,13 +2525,13 @@ $(document).ready(function() {
font-style: italic !important;
color: #2a00ff !important;
}
</style><style type="text/css">html{margin:0;padding:0;}h1{margin:0;padding:0;}h2{margin:0;padding:0;}h3{margin:0;padding:0;}h4{margin:0;padding:0;}a{color:#261A3B;}a:visited{color:#261A3B;}</style><style type="text/css">.header{margin-top:30px;}h1.project-name{font-size:34px;display:inline;}h2.project-version{font-size:18px;margin-top:0;display:inline;margin-left:10px;}.toc-link{font-size:12px;margin-left:10px;color:#252519;text-decoration:none;}.toc-link:hover{color:#5050A6;}.toc h1{font-size:34px;margin:0;}.docs-header{border-bottom:dotted #aaa 1px;padding-bottom:10px;margin-bottom:25px;}.toc h1{font-size:24px;}.toc{border-bottom:solid #bbb 1px;margin-bottom:40px;}.toc ul{margin-left:20px;padding-left:0px;padding-top:0;margin-top:0;}.toc li{list-style-type:none;padding-left:0;}.dependencies{}.dependencies table{font-size:16px;width:99.99%;border:none;margin-left:20px;}.dependencies td{padding-right:20px;;white-space:nowrap;}.dependencies .dotted{width:99%;}.dependencies .dotted hr{margin-bottom:-6px;noshade:noshade;border-top:none;color:transparent;border-left:none;border-bottom:dotted #bbb 1px;border-right:none;background-color:transparent;height:0;}.dependencies .dep-version{text-align:right;}.plugins ul{margin-left:20px;padding-left:0px;padding-top:0;margin-top:0;}.plugins li{list-style-type:none;padding-left:0;}.header p{margin-left:20px;}</style><style type="text/css">#floating-toc{position:fixed;top:10px;right:20px;height:20px;overflow:hidden;text-align:right;}#floating-toc li{list-style-type:none;margin:0;padding:0;}</style><style type="text/css">body{margin:0;padding:0;font-family:'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif;;font-size:16px;color:#252519;}h1{font-size:20px;margin-top:0;}a.anchor{text-decoration:none;color:#252519;}a.anchor:hover{color:#5050A6;}table{border-spacing:0;border-bottom:solid #ddd 1px;;margin-bottom:10px;}code{display:inline;}p{margin-top:8px;}tr{margin:0px;padding:0px;}td.docs{width:410px;max-width:410px;vertical-align:top;margin:0px;padding-left:55px;padding-right:20px;border:none;}td.docs pre{font-size:12px;overflow:hidden;}td.codes{border:none;margin:0px;padding-left:20px;width:55%;border-left:solid #E5E5EE 1px;font-size:10pt;vertical-align:top;overflow:hidden;background-color:#F5F5FF;}td.spacer{padding-bottom:40px;}pre code{display:block;padding:4px;}code{background-color:ghostWhite;border:solid #DEDEDE 1px;padding-left:3px;padding-right:3px;font-size:14px;}.syntaxhighlighter code{font-size:13px;}.footer{text-align:center;}</style><script src="mathjax/MathJax.js" type="text/javascript"></script><title>Marginalia Output</title></head><body><table><tr><td class="docs"><div class="header"><h1 class="project-name">marginalia</h1><h2 class="project-version">0.2.3</h2><br /><p>lightweight literate programming for clojure -- inspired by <a href="http://jashkenas.github.com/docco/">docco</a></p>
</div><div class="dependencies"><h3>dependencies</h3><table><tr><td class="dep-name">org.clojure/clojure</td><td class="dotted"><hr /></td><td class="dep-version">1.2.0</td></tr><tr><td class="dep-name">org.clojars.nakkaya/markdownj</td><td class="dotted"><hr /></td><td class="dep-version">1.0.2b4</td></tr><tr><td class="dep-name">hiccup</td><td class="dotted"><hr /></td><td class="dep-version">0.3.0</td></tr></table></div><div class="dependencies"><h3>dev dependencies</h3><table><tr><td class="dep-name">lein-clojars</td><td class="dotted"><hr /></td><td class="dep-version">0.5.0-SNAPSHOT</td></tr><tr><td class="dep-name">jline</td><td class="dotted"><hr /></td><td class="dep-version">0.9.94</td></tr><tr><td class="dep-name">swank-clojure</td><td class="dotted"><hr /></td><td class="dep-version">1.2.1</td></tr><tr><td class="dep-name">hiccup</td><td class="dotted"><hr /></td><td class="dep-version">0.3.0</td></tr><tr><td class="dep-name">org.clojars.nakkaya/markdownj</td><td class="dotted"><hr /></td><td class="dep-version">1.0.2b4</td></tr><tr><td class="dep-name">marginalia</td><td class="dotted"><hr /></td><td class="dep-version">0.2.3</td></tr></table></div><div class="plugins"><h3>cake plugin namespaces</h3><ul><li>marginalia.tasks</li></ul></div></td><td class="codes" style="text-align: center; vertical-align: middle;color: #666;padding-right:20px"><br /><br /><br />(this space intentionally left blank)</td></tr><tr><td class="docs"><div class="toc"><a name="toc"><h3>namespaces</h3></a><ul><li><a href="#leiningen.marg">leiningen.marg</a></li><li><a href="#marginalia.core">marginalia.core</a></li><li><a href="#marginalia.html">marginalia.html</a></li><li><a href="#marginalia.tasks">marginalia.tasks</a></li><li><a href="#problem-cases.general">problem-cases.general</a></li></ul></div></td><td class="codes">&nbsp;</td></tr><tr><td class="docs"><div class="docs-header"><a class="anchor" href="#leiningen.marg" name="leiningen.marg"><h1 class="project-name">leiningen.marg</h1><a class="toc-link" href="#toc">toc</a></a></div></td><td class="codes" /></tr><tr><td class="docs"><h1>Leiningen plugin for running marginalia against your project.</h1>
</style><style type="text/css">html{margin:0;padding:0;}h1{margin:0;padding:0;}h2{margin:0;padding:0;}h3{margin:0;padding:0;}h4{margin:0;padding:0;}a{color:#261A3B;}a:visited{color:#261A3B;}</style><style type="text/css">.header{margin-top:30px;}h1.project-name{font-size:34px;display:inline;}h2.project-version{font-size:18px;margin-top:0;display:inline;margin-left:10px;}.toc-link{font-size:12px;margin-left:10px;color:#252519;text-decoration:none;}.toc-link:hover{color:#5050A6;}.toc h1{font-size:34px;margin:0;}.docs-header{border-bottom:dotted #aaa 1px;padding-bottom:10px;margin-bottom:25px;}.toc h1{font-size:24px;}.toc{border-bottom:solid #bbb 1px;margin-bottom:40px;}.toc ul{margin-left:20px;padding-left:0px;padding-top:0;margin-top:0;}.toc li{list-style-type:none;padding-left:0;}.dependencies{}.dependencies table{font-size:16px;width:99.99%;border:none;margin-left:20px;}.dependencies td{padding-right:20px;;white-space:nowrap;}.dependencies .dotted{width:99%;}.dependencies .dotted hr{margin-bottom:-6px;noshade:noshade;border-top:none;color:transparent;border-left:none;border-bottom:dotted #bbb 1px;border-right:none;background-color:transparent;height:0;}.dependencies .dep-version{text-align:right;}.plugins ul{margin-left:20px;padding-left:0px;padding-top:0;margin-top:0;}.plugins li{list-style-type:none;padding-left:0;}.header p{margin-left:20px;}</style><style type="text/css">#floating-toc{position:fixed;top:10px;right:20px;height:20px;overflow:hidden;text-align:right;}#floating-toc li{list-style-type:none;margin:0;padding:0;}</style><style type="text/css">body{margin:0;padding:0;font-family:'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif;;font-size:16px;color:#252519;}h1{font-size:20px;margin-top:0;}a.anchor{text-decoration:none;color:#252519;}a.anchor:hover{color:#5050A6;}table{border-spacing:0;border-bottom:solid #ddd 1px;;margin-bottom:10px;}code{display:inline;}p{margin-top:8px;}tr{margin:0px;padding:0px;}td.docs{width:410px;max-width:410px;vertical-align:top;margin:0px;padding-left:55px;padding-right:20px;border:none;}td.docs pre{font-size:12px;overflow:hidden;}td.codes{border:none;margin:0px;padding-left:20px;width:55%;border-left:solid #E5E5EE 1px;font-size:10pt;vertical-align:top;overflow:hidden;background-color:#F5F5FF;}td.spacer{padding-bottom:40px;}pre code{display:block;padding:4px;}code{background-color:ghostWhite;border:solid #DEDEDE 1px;padding-left:3px;padding-right:3px;font-size:14px;}.syntaxhighlighter code{font-size:13px;}.footer{text-align:center;}</style><script src="mathjax/MathJax.js" type="text/javascript"></script><title>Marginalia Output</title></head><body><table><tr><td class="docs"><div class="header"><h1 class="project-name">marginalia</h1><h2 class="project-version">0.3.0</h2><br /><p>lightweight literate programming for clojure -- inspired by <a href="http://jashkenas.github.com/docco/">docco</a></p>
</div><div class="dependencies"><h3>dependencies</h3><table><tr><td class="dep-name">org.clojure/clojure</td><td class="dotted"><hr /></td><td class="dep-version">1.2.0</td></tr><tr><td class="dep-name">org.clojars.nakkaya/markdownj</td><td class="dotted"><hr /></td><td class="dep-version">1.0.2b4</td></tr><tr><td class="dep-name">hiccup</td><td class="dotted"><hr /></td><td class="dep-version">0.3.0</td></tr></table></div><div class="dependencies"><h3>dev dependencies</h3><table><tr><td class="dep-name">lein-clojars</td><td class="dotted"><hr /></td><td class="dep-version">0.5.0-SNAPSHOT</td></tr><tr><td class="dep-name">jline</td><td class="dotted"><hr /></td><td class="dep-version">0.9.94</td></tr><tr><td class="dep-name">swank-clojure</td><td class="dotted"><hr /></td><td class="dep-version">1.2.1</td></tr><tr><td class="dep-name">hiccup</td><td class="dotted"><hr /></td><td class="dep-version">0.3.0</td></tr><tr><td class="dep-name">org.clojars.nakkaya/markdownj</td><td class="dotted"><hr /></td><td class="dep-version">1.0.2b4</td></tr><tr><td class="dep-name">marginalia</td><td class="dotted"><hr /></td><td class="dep-version">0.3.0</td></tr></table></div><div class="plugins"><h3>cake plugin namespaces</h3><ul><li>marginalia.tasks</li></ul></div></td><td class="codes" style="text-align: center; vertical-align: middle;color: #666;padding-right:20px"><br /><br /><br />(this space intentionally left blank)</td></tr><tr><td class="docs"><div class="toc"><a name="toc"><h3>namespaces</h3></a><ul><li><a href="#leiningen.marg">leiningen.marg</a></li><li><a href="#marginalia.core">marginalia.core</a></li><li><a href="#marginalia.html">marginalia.html</a></li><li><a href="#marginalia.tasks">marginalia.tasks</a></li><li><a href="#problem-cases.general">problem-cases.general</a></li></ul></div></td><td class="codes">&nbsp;</td></tr><tr><td class="docs"><div class="docs-header"><a class="anchor" href="#leiningen.marg" name="leiningen.marg"><h1 class="project-name">leiningen.marg</h1><a class="toc-link" href="#toc">toc</a></a></div></td><td class="codes" /></tr><tr><td class="docs"><h1>Leiningen plugin for running marginalia against your project.</h1>
<h2>Usage</h2>
<ol>
<li>Add <code>[marginalia "0.2.3"]</code> to your project.clj's <code>:dev-dependencies</code> section.</li>
<li>Add <code>[marginalia "&amp;lt;current version number&amp;gt;"]</code> to your project.clj's <code>:dev-dependencies</code> section.</li>
<li>run <code>lein marg</code> from your project's root directory.</li>
</ol>
</td><td class="codes"><pre class="brush: clojure">(ns leiningen.marg
@ -2687,7 +2687,19 @@ current line start with a quote?</p>
(and (re-find #&quot;^\(deftask&quot; (str/trim last-code-text))</pre></td></tr><tr><td class="docs"><p>Is the last line's code-text the start of a ns
decl, and does the current line start with a quote?</p>
</td><td class="codes"><pre class="brush: clojure"> (re-find #&quot;^\&quot;&quot; (str/trim (str line))))
(and (re-find #&quot;^\(ns&quot; last-code-text)</pre></td></tr><tr><td class="docs"><p>Is the prev line a docstring, prev line not end with a quote,
(and (re-find #&quot;^\(ns&quot; last-code-text)</pre></td></tr><tr><td class="docs"><p>Is the last line's code-text the start of a defprotocol,
and does the current line start with a quote?</p>
</td><td class="codes"><pre class="brush: clojure"> (re-find #&quot;^\&quot;&quot; (str/trim (str line))))
(and (re-find #&quot;^\(defprotocol&quot; last-code-text)</pre></td></tr><tr><td class="docs"><p>Is the last line's code-text the start of a defmulti,
and does the current line start with a quote?</p>
</td><td class="codes"><pre class="brush: clojure"> (re-find #&quot;^\&quot;&quot; (str/trim (str line))))
(and (re-find #&quot;^\(defmulti&quot; last-code-text)</pre></td></tr><tr><td class="docs"><p>Is the last line's code-text the start of a defmethod,
and does the current line start with a quote?</p>
</td><td class="codes"><pre class="brush: clojure"> (re-find #&quot;^\&quot;&quot; (str/trim (str line))))
(and (re-find #&quot;^\(defmethod&quot; last-code-text)</pre></td></tr><tr><td class="docs"><p>Is the last line's code-text the start of a defmacro,
and does the current line start with a quote?</p>
</td><td class="codes"><pre class="brush: clojure"> (re-find #&quot;^\&quot;&quot; (str/trim (str line))))
(and (re-find #&quot;^\(defmacro&quot; last-code-text)</pre></td></tr><tr><td class="docs"><p>Is the prev line a docstring, prev line not end with a quote,
and the current line empty?</p>
</td><td class="codes"><pre class="brush: clojure"> (re-find #&quot;^\&quot;&quot; (str/trim (str line))))
(and (:docstring-text l)</pre></td></tr><tr><td class="docs"><p>Is the prev line a docstring, the prev line not end with a quote,
@ -2785,8 +2797,7 @@ I wonder?</p>
(ensure-directory! &quot;./docs&quot;)
(uberdoc! &quot;./docs/uberdoc.html&quot; sources)
(println &quot;Done generating your docs, please see ./docs/uberdoc.html&quot;)
(println)))))</pre></td></tr><tr><td class="docs"><p>main docstring
Multi line</p>
(println)))))</pre></td></tr><tr><td class="docs"><p>The main entry point into Marginalia.</p>
</td><td class="codes"><pre class="brush: clojure">
(defn -main
[&amp; sources]
@ -2800,8 +2811,8 @@ Multi line</p>
</td><td class="codes"><pre class="brush: clojure">
(merge-line {:docstring-text &quot;hello world&quot; :line 3} {:docs [&quot;stuff&quot;]})
(merge-line {:code-text &quot;(defn asdf&quot; :line 4} {:docs [&quot;stuff&quot;]})
(merge-line {:docs-text &quot;There's only one method in this module&quot;, :line 4} {}))
</pre></td></tr><tr><td class="spacer docs">&nbsp;</td><td class="codes" /></tr><tr><td class="docs"><div class="docs-header"><a class="anchor" href="#marginalia.html" name="marginalia.html"><h1 class="project-name">marginalia.html</h1><a class="toc-link" href="#toc">toc</a></a></div></td><td class="codes" /></tr><tr><td class="docs"><h1>Utilities for converting parse results into html.</h1>
(merge-line {:docs-text &quot;There's only one method in this module&quot;, :line 4} {})
)</pre></td></tr><tr><td class="spacer docs">&nbsp;</td><td class="codes" /></tr><tr><td class="docs"><div class="docs-header"><a class="anchor" href="#marginalia.html" name="marginalia.html"><h1 class="project-name">marginalia.html</h1><a class="toc-link" href="#toc">toc</a></a></div></td><td class="codes" /></tr><tr><td class="docs"><h1>Utilities for converting parse results into html.</h1>
<h2>Plus a few other goodies.</h2>
@ -3151,6 +3162,7 @@ saying that all this is WIP and will prabably change in the future.</p>
(doctype :html5)
[:html
[:head
[:meta {:http-equiv &quot;Content-Type&quot; :content &quot;text/html&quot; :charset &quot;utf-8&quot;}]
(inline-js &quot;jquery-1.4.4.min.js&quot;)
(inline-js &quot;xregexp-min.js&quot;)
(inline-js &quot;shCore.js&quot;)
@ -3202,7 +3214,7 @@ It's probably the only var consumers will use.</p>
<h2>Usage</h2>
<ol>
<li>In your project.clj, add <code>[marginalia "0.2.3"] to your</code>:dev-dependencies<code>and</code>marginalia.tasks<code>to</code>:tasks`</li>
<li>In your project.clj, add <code>[marginalia "&amp;lt;current version number&amp;gt;"] to your</code>:dev-dependencies<code>and</code>marginalia.tasks<code>to</code>:tasks`</li>
<li>Run <code>cake marg</code> from within your project directory.</li>
</ol>
</td><td class="codes"><pre class="brush: clojure">(ns marginalia.tasks
@ -3231,7 +3243,25 @@ See <a href="https://github.com/fogus/marginalia/issues/#issue/4">https://github
(defn b-function
[x]
&quot;Here is just a string. It should be to the right.&quot;
(* x x))</pre></td></tr><tr><td class="docs">
(* x x))</pre></td></tr><tr><td class="docs"><p>This is a macro docstring. It should be on the left.</p>
</td><td class="codes"><pre class="brush: clojure">
(defmacro foobar
[&amp; body]
`~body)</pre></td></tr><tr><td class="docs"><p>This is a defmulti docstring, it should also be on the left</p>
</td><td class="codes"><pre class="brush: clojure">
(defmulti bazfoo
class)</pre></td></tr><tr><td class="docs"><p>This is a defmethod docstring. It should be on the left.</p>
</td><td class="codes"><pre class="brush: clojure">
(defmethod bazfoo String [s]
(vec (seq s)))
(bazfoo &quot;abc&quot;)</pre></td></tr><tr><td class="docs"><p>This is a protocol docstring. It should be on the left.</p>
</td><td class="codes"><pre class="brush: clojure">
(defprotocol Foo
(lookup [cache e])
(has? [cache e] )
(hit [cache e])
(miss [cache e ret]))</pre></td></tr><tr><td class="docs">
</td><td class="codes"><pre class="brush: clojure">
(def ^{:doc &quot;This is also a docstring via metadata. It should be on the left.&quot;}
a 42)</pre></td></tr><tr><td class="docs">
@ -3272,4 +3302,4 @@ See <a href="https://github.com/fogus/marginalia/issues/#issue/4">https://github
pageTracker._trackPageview();
} catch(err) {}
</script>
</body></html>
</body></html>

2
src/leiningen/marg.clj
View file

@ -3,7 +3,7 @@
## Usage
1. Add `[marginalia \"0.2.4\"]` to your project.clj's `:dev-dependencies` section.
1. Add `[marginalia \"<current version number>\"]` to your project.clj's `:dev-dependencies` section.
2. run `lein marg` from your project's root directory. "
(:use [marginalia.core]))

12
src/marginalia/core.clj
View file

@ -147,7 +147,19 @@
;; Is the last line's code-text the start of a defprotocol,
;; and does the current line start with a quote?
(and (re-find #"^\(defprotocol" last-code-text)
(re-find #"^\"" (str/trim (str line))))
;; Is the last line's code-text the start of a defmulti,
;; and does the current line start with a quote?
(and (re-find #"^\(defmulti" last-code-text)
(re-find #"^\"" (str/trim (str line))))
;; Is the last line's code-text the start of a defmethod,
;; and does the current line start with a quote?
(and (re-find #"^\(defmethod" last-code-text)
(re-find #"^\"" (str/trim (str line))))
;; Is the last line's code-text the start of a defmacro,
;; and does the current line start with a quote?
(and (re-find #"^\(defmacro" last-code-text)
(re-find #"^\"" (str/trim (str line))))
;; Is the prev line a docstring, prev line not end with a quote,
;; and the current line empty?
(and (:docstring-text l)

2
src/marginalia/tasks.clj
View file

@ -3,7 +3,7 @@
## Usage
1. In your project.clj, add `[marginalia \"0.2.4\"] to your `:dev-dependencies` and `marginalia.tasks` to `:tasks`
1. In your project.clj, add `[marginalia \"<current version number>\"] to your `:dev-dependencies` and `marginalia.tasks` to `:tasks`
2. Run `cake marg` from within your project directory."
(:use marginalia.core
[cake.core :only [deftask]]))

17
src/problem_cases/general.clj
View file

@ -21,7 +21,22 @@
"Here is just a string. It should be to the right."
(* x x))
(defprotocol CacheProtocol
(defmacro foobar
"This is a macro docstring. It should be on the left."
[& body]
`~body)
(defmulti bazfoo
"This is a defmulti docstring, it should also be on the left"
class)
(defmethod bazfoo String [s]
"This is a defmethod docstring. It should be on the left."
(vec (seq s)))
(bazfoo "abc")
(defprotocol Foo
"This is a protocol docstring. It should be on the left."
(lookup [cache e])
(has? [cache e] )