Adding directives to selectively disable comment parsing.
This change adds so-called 'directives' to our comments. A directive is a comment line whose only contents are a hash, followed by the directive name, e.g. ``` ;; #DirectiveName ``` Directives are not included in the `*comments*` vector in any case. The two directives implemented here are "#MargDisable" and "#MargEnable". The former, when encountered, causes comments read by `read-comment` to be ignored. The latter re-enables it. The rationale for this change is to accommodate e.g. license-header boilerplate without polluting the generated docs.
This commit is contained in:
parent
17c75832de
commit
7e1eee7ff7
1 changed files with 39 additions and 6 deletions
|
@ -42,6 +42,36 @@
|
||||||
(def sub-level-comments (atom []))
|
(def sub-level-comments (atom []))
|
||||||
|
|
||||||
(def ^{:dynamic true} *comments* nil)
|
(def ^{:dynamic true} *comments* nil)
|
||||||
|
(def ^{:dynamic true} *comments-enabled* nil)
|
||||||
|
|
||||||
|
(defn comments-enabled?
|
||||||
|
[]
|
||||||
|
@*comments-enabled*)
|
||||||
|
|
||||||
|
(def directives
|
||||||
|
"Marginalia can be given directives in comments. A directive is a comment
|
||||||
|
line containing a directive name, in the form `;; #DirectiveName`.
|
||||||
|
Directives change the behavior of the parser within the files that contain
|
||||||
|
them.
|
||||||
|
|
||||||
|
The following directives are defined:
|
||||||
|
|
||||||
|
* `#MargDisable` suppresses subsequent comments from the docs
|
||||||
|
* `#MargEnable` includes subsequent comments in the docs"
|
||||||
|
{"MargDisable" (fn [] (swap! *comments-enabled* (constantly false)))
|
||||||
|
"MargEnable" (fn [] (swap! *comments-enabled* (constantly true)))})
|
||||||
|
|
||||||
|
(defn process-directive!
|
||||||
|
"If the given line is a directive, applies it. Returns a value
|
||||||
|
indicating whether the line should be included in the comments
|
||||||
|
list."
|
||||||
|
[line]
|
||||||
|
(let [directive (->> (re-find #"^;+\s*#(\w+)" line)
|
||||||
|
(last)
|
||||||
|
(get directives))]
|
||||||
|
(when directive
|
||||||
|
(directive))
|
||||||
|
(not directive)))
|
||||||
|
|
||||||
(defn read-comment [reader semicolon]
|
(defn read-comment [reader semicolon]
|
||||||
(let [sb (StringBuilder.)]
|
(let [sb (StringBuilder.)]
|
||||||
|
@ -50,11 +80,13 @@
|
||||||
(let [ch (char c)]
|
(let [ch (char c)]
|
||||||
(if (or (= ch \newline)
|
(if (or (= ch \newline)
|
||||||
(= ch \return))
|
(= ch \return))
|
||||||
(let [line (dec (.getLineNumber reader))]
|
(let [line (dec (.getLineNumber reader))
|
||||||
(swap! *comments* conj
|
text (.toString sb)
|
||||||
{:form (Comment. (.toString sb))
|
include? (process-directive! text)]
|
||||||
|
(when (and include? (comments-enabled?))
|
||||||
|
(swap! *comments* conj {:form (Comment. text)
|
||||||
:start line
|
:start line
|
||||||
:end line})
|
:end line}))
|
||||||
reader)
|
reader)
|
||||||
(do
|
(do
|
||||||
(.append sb (Character/toString ch))
|
(.append sb (Character/toString ch))
|
||||||
|
@ -363,5 +395,6 @@
|
||||||
(let [readers (if (cljs-file? file)
|
(let [readers (if (cljs-file? file)
|
||||||
(->> default-data-readers (merge *cljs-data-readers*))
|
(->> default-data-readers (merge *cljs-data-readers*))
|
||||||
default-data-readers)]
|
default-data-readers)]
|
||||||
(binding [*data-readers* readers]
|
(binding [*data-readers* readers
|
||||||
|
*comments-enabled* (atom true)]
|
||||||
(parse (slurp file)))))
|
(parse (slurp file)))))
|
||||||
|
|
Loading…
Reference in a new issue