proof of concept for attaching :doc metadata to generate functions

[behrica]

This is very draft.
I was not able to re-use the existing "help" , and need a hack to have a session.
And on this I am not sure, how to do better.

[behrica]

@genmeblog, maybe you can improve on it.

[behrica]

I removed the duplication of the help logic.
Not 100% sure, if I pass the "session" around correctly.
But it does work now.

BUT its slow.
It increases quite a lot the time of require-r, not sure if something can be done.
I noticed as well that "Calva" is not able to render tgis type o dynamic ":doc".
Emacs does, and repl shows them as well yuing (doc ...)

[behrica]

Can be used like this:

(reset! clojisr.v1.require/attach-help-as-docstring-to-vars true)
(r/require-r '[ggplot2])
(r/require-r '[ranger])
(r/require-r '[base])

Help generation is as well memoized, so at least fast on second call

[behrica]

It does work as well for Calva, not sure why it failed as I tried.

[genmeblog]

Maybe instead of attach-help-as-docstring-to-vars add an option to require-r itself?

(require-r '[ggplot :docs? true])

[behrica]

Maybe instead of attach-help-as-docstring-to-vars add an option to require-r itself?

(require-r '[ggplot :docs? true])

Yes, I thought about it.
Not sure, what best.

Ideally we could speed it up..., but likely not possible.
To mee it something you "either want" or "don't want".

Not per library.

[genmeblog]

Yes, you're right, so maybe an argument to require-r itself?

[behrica]

FYI:
Currently there is a bug in VSCode / Calva which prevents the rendering of this help attached to the vars.
BetterThanTomorrow/calva#2552
But it seems fixable, as Calva has already foreseen to take doc from Cider and not only from LSP.
LSP is not informed about such dynamic vars, so cannot report this doc strings.

[behrica]

In my view the "slow R package loading" due to help loading is acceptable, as it happens only once per R package, then its cached.
So maybe an atom to switch it on/off is enough.
Or we make it "delayed", So we do an "immediate loading" without help,
and the we load again on an other thread in a background.

[genmeblog]

We can also alter vars in the background I think.

[behrica]

I am pretty happy with it now.

The :doc gets now changed to be "help" via alter-meta! in a future, always.
This is transparent for the user in most cases, as in repl the require returns immediately.
and a few seconds later, the doc string of the var is updated, and IDEs should show it.

[behrica]

Remark: as we use now a "future" we get the 60 seconds waiting when clojure shuts down

[genmeblog]

Remark: as we use now a "future" we get the 60 seconds waiting when clojure shuts down

Strange, futures shouldn't affect the shutdown time...

[behrica]

Remark: as we use now a "future" we get the 60 seconds waiting when clojure shuts down

Strange, futures shouldn't affect the shutdown time...

Yes, they do.
https://clojure.atlassian.net/browse/CLJ-124

[genmeblog]

Ok. I see. What about add a (shutdown-agents) here: https://github.com/scicloj/clojisr/blob/master/src/clojisr/v1/r.clj#L201 ?

[behrica]

Ok. I see. What about add a (shutdown-agents) here: https://github.com/scicloj/clojisr/blob/master/src/clojisr/v1/r.clj#L201 ?

Will not make a difference, as this hook is called "too late as well" , I suppose.
I will research if some other "parallel executors" do not have this issue.

[genmeblog]

When does this 60s delay happen? I mean what cases are affected?

[behrica]

When does this 60s delay happen? I mean what cases are affected?

In practice only in units tests...or when running "clj -e ' ' ".
In interactive REPL work, the JVM is up for hours, and "exiting" it kills the daemon threads.
So "scripts" could be affected, not sure anybody doe stehm with ClojisR.

[behrica]

time clj -e "(require '[clojisr.v1.r :as r])(r/require-r '[utils])"

real    1m10.797s
user    0m29.738s
sys     0m0.844s

Here we see the 60 seconds delay.

vs

time clj -e "(require '[clojisr.v1.r :as r])(r/require-r '[utils])(System/exit 0)"
real    0m14.728s
user    0m29.386s
sys     0m0.827s

same duration as:

time clj -e "(require '[clojisr.v1.r :as r])(r/require-r '[utils])(shutdown-agents)"

real    0m15.212s
user    0m29.055s
sys     0m0.767s

So people doing scripts just need to remember to add it.

[genmeblog]

Why do we need this (ie. returned symbol)?

[behrica]

Looks like mistake. Will fix in next commit.

[genmeblog]

future runs just after symbols are interned - do we need this 5sec waiting time?

[behrica]

Without it we have a noticeably lag in IDE when interactively evaluating a 'require-r'