Understanding Marginalia's Behaviour

[Ian Phillips]

OK, first question on the list:

Why is it that marg sometimes decides to display a function's doc-string in the margin and sometimes leaves it in the source code column? Is there a way to control where it displays, or at least have it always display in the margin?

Cheers,

Ian.

[Fogus]

There are some points about intergrating with Lein that I haven't yet
noodled through, but I'll take some time in the next few days to
figure it out. There is a ticket that I think is related at
https://github.com/fogus/marginalia/issues/55.

[Zachary Kim]

Looks like a problem in the parser, working on a topic branch here:

 https://github.com/fogus/marginalia/tree/issue-0055-dosent-like-certain-requires

[Jeff]

Glad this was brought up! I'd found it a bit puzzling.

With Marginalia 0.3.2, running `lein marg` seems to work fine--
docstrings land in the margin as expected. With any newer numbered
release, both the lein-marginalia plugin and the standalone jar leave
(most though sometimes not the first few) docstrings in the code
column.

- Jeff

[semperos]

I've experienced the same thing. Here's an example for one of my projects:

http://techylinguist.com/project-static/clj-webdriver/uberdoc.html

[Sebastián Galkin]

Don't know if  this may help but I also had this problem, only when using clj 1.3.0-beta1. The problem disappeared using clj 1.2.1, but maybe was because I needed to change some requires to use 1.2.1

[Pierre-Yves Ritschard]

I'm seeing the same problem, even on small projects, what usage
prevents the parsing to fail ? I do use (:require [s.s.s :as s]) a
lot, is that the culprit ?

[Gergely Nagy]

(looks like the group ate my former mail... perhaps held for
moderation, resending my thoughts from my subscribed address)

Nope, (:require [s.s.s :as s] in itself is not the culrpit. For
example (:require [clojure.contrib.str-utils2 :as s]) does not break
Marginalia, while (:require [clj-time.format :as tf]) does. I haven't
yet found out what's common in the requires that do break it.

--
|8]

[Ian Phillips]

I can confirm that I'm running under 1.3.0 β1 (and am not using require anywhere).

[Fogus]

> With Marginalia 0.3.2, running `lein marg` seems to work fine--

The 0.3.2 version was the initial cut based solely on regular
expressions. Since 0.3.2 the parser has gotten decidedly smarter and
more extensible, but apparently not without cost. My suspicions are
that there is a Clojure version issue at play between the version used
for Marg and the given libraries being required. This is a theory
however. We'll figure it out. My advice for now is that if the docs
seem to be emitted improperly then to fall back on 0.3.2 until we sort
things out.
:F

[sinistral]

For what its worth, I've run into this problem this morning with
Marginalia 0.6.1 and it seems to me that Marginalia doesn't pull
docstrings onto the left for Clojure source files that are not in the
default lein project tree. When I have source files in ./src/
clojure/... and not ./src/... I see this behaviour. If I move them
to ./src/... then everything works as expected.

.marc