Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Address #15 by adding --lift-inline-comments option #169

Merged
merged 3 commits into from
Nov 10, 2017
Merged

Address #15 by adding --lift-inline-comments option #169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
08f7c20
Address #15 by adding --lift-inline-comments option
seancorfield Nov 10, 2017
a252dec
Further work on #15 to ensure each block of inline comments is its ow…
seancorfield Nov 10, 2017
fa15dfd
More #15 -- this ensures a paragraph break _before_ the first inline …
seancorfield Nov 10, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions src/marginalia/core.clj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
[clojure.string :as str])
(:use [marginalia
[html :only (uberdoc-html index-html single-page-html)]
[parser :only (parse-file parse-ns)]]
[parser :only (parse-file parse-ns *lift-inline-comments*)]]
[clojure.tools
[cli :only (cli)]]))

Expand Down Expand Up @@ -256,7 +256,8 @@

If no source files are found, complain with a usage message."
[args & [project]]
(let [[{:keys [dir file name version desc deps css js multi leiningen exclude]} files help]
(let [[{:keys [dir file name version desc deps css js multi
leiningen exclude lift-inline-comments]} files help]
(cli args
["-d" "--dir" "Directory into which the documentation will be written" :default "./docs"]
["-f" "--file" "File into which the documentation will be written" :default "uberdoc.html"]
Expand All @@ -272,14 +273,16 @@
["-m" "--multi" "Generate each namespace documentation as a separate file" :flag true]
["-l" "--leiningen" "Generate the documentation for a Leiningen project file."]
["-e" "--exclude" "Exclude source file(s) from the document generation process <file1>;<file2>;...
If not given will be taken from project.clj"])
If not given will be taken from project.clj"]
["-L" "--lift-inline-comments" "Lift ;; inline comments to the top of the enclosing form.
They will be treated as if they preceded the enclosing form." :flag true])
sources (distinct (format-sources (seq files)))
sources (if leiningen (cons leiningen sources) sources)]
(if-not sources
(do
(println "Wrong number of arguments passed to Marginalia.")
(println help))
(binding [*docs* dir]
(binding [*docs* dir *lift-inline-comments* lift-inline-comments]
(let [project-clj (or project
(when (.exists (io/file "project.clj"))
(parse-project-file)))
Expand Down
33 changes: 28 additions & 5 deletions src/marginalia/parser.clj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,12 @@
;; Extracted from clojure.contrib.reflect
(defn call-method
"Calls a private or protected method.

params is a vector of classes which correspond to the arguments to
the method e

obj is nil for static methods, the instance object otherwise.

The method-name is given a symbol or a keyword (something Named)."
[klass method-name params obj & args]
(-> klass (.getDeclaredMethod (name method-name)
Expand All @@ -44,6 +44,7 @@

(def ^{:dynamic true} *comments* nil)
(def ^{:dynamic true} *comments-enabled* nil)
(def ^{:dynamic true} *lift-inline-comments* nil)

(defn comments-enabled?
[]
Expand Down Expand Up @@ -158,6 +159,9 @@
(recur (.read rdr))
:else (.unread rdr c))))

(declare adjacent?)
(declare merge-comments)

(defn parse* [reader]
(take-while
#(not= :_eof (:form %))
Expand All @@ -181,8 +185,27 @@
(throw e)))))
end (.getLineNumber reader)
code {:form form :start start :end end}
comments @top-level-comments]
;; We optionally lift inline comments to the top of the form.
;; This monstrosity ensures that each consecutive group of inline
;; comments is treated as a mergable block, but with a fake
;; blank comment between non-adjacent inline comments. When merged
;; and converted to markdown, this will produce a paragraph for
;; each separate block of inline comments.
paragraph-comment {:form (Comment. ";;")} ; start/end added below
inline-comments (when *lift-inline-comments*
(->> @sub-level-comments
(reduce (fn [cs c]
(if-let [t (peek cs)]
(if (adjacent? t c)
(conj cs c)
(conj cs paragraph-comment c))
(conj cs c)))
[])
(into [paragraph-comment])
(mapv #(assoc % :start start :end (dec start)))))
comments (concat @top-level-comments inline-comments)]
(swap! top-level-comments (constantly []))
(swap! sub-level-comments (constantly []))
(if (empty? comments)
[code]
(vec (concat comments [code])))))))))
Expand Down Expand Up @@ -297,7 +320,7 @@
(defn- literal-form? [form]
(or (string? form) (number? form) (keyword? form) (symbol? form)
(char? form) (true? form) (false? form) (instance? java.util.regex.Pattern form)))

(defmethod dispatch-form :default
[form raw nspace-sym]
(cond (literal-form? form)
Expand Down