marginalia
marginalia copied to clipboard
clj-commons
How to handle nested comments?
With the latest fix for the parser, it now has been improved to handle top-level versus nested comments. For the moment, it leaves them untouched. I wonder if we could make Marginalia do something clever with them, any suggestions?
By nested, do you mean this:
;; this is top-level
(defn foo [x]
;; this is nested
42)
??
Yes, exactly! We can just not care about them, but the latest changes to the parser add the possibility to do something with them.
My view is:
(defn foo [x]
;; sub-comments alone on a line go to the doc view (left-side)
(let [x (int x)] ;; comments at the end of code stay in the code (right-side)
x))
What do you think?
Seems reasonable, but for the lone sub-comments, do we just append it to the current code block docs or do we split the code block? The first case should be easier to implement, the second have the advantage of keeping the comment aligned with it's content.
Keeping the comment aligned with its content is the way that Docco works, so there is no reason to change that I think. You can see how Docco does it at http://jashkenas.github.com/docco/#section-11
I'll probably work on this only next week as I've started a new contract and I'm pretty busy this week. Also I'd like to test Marginalia output on Pallet, Hugo told me about some issues with it's project output.
