proof of concept for attaching :doc metadata to generate functions

.gitignore

@@ -18,3 +18,4 @@ pom.xml.asc
 .clay*
 *qmd
 .clerk
+.calva

src/clojisr/v1/help.clj

@@ -0,0 +1,28 @@
+(ns clojisr.v1.help
+  (:require [clojisr.v1.eval :as evl]
+            [clojisr.v1.using-sessions :as using-sessions]
+            [clojisr.v1.impl.java-to-clj :as java2clj]
+            [clojure.string :as str]
+            ))
+
+
+(defn _help
+  "Gets help for an R object or function"
+  ([r-object session]
+   (let [symbol (second  (re-find #"\{(.*)\}" (:code r-object)))
+         split (str/split symbol #"::")]
+
+     (_help (second split) (first split) session)))
+
+  ([function package session]
+
+   (->>
+    (evl/r (format  "capture.output(tools:::Rd2txt(utils:::.getHelpFile(as.character(help(%s,%s))), options=list(underline_titles=FALSE)))"
+                    (name function) (name package))
+           session)
+
+    (using-sessions/r->java)
+    (java2clj/java->clj)
+    (str/join "\n"))))
+
+(def help (memoize _help))

src/clojisr/v1/r.clj

@@ -9,9 +9,11 @@
             [clojisr.v1.impl.java-to-clj :as java2clj]
             [clojisr.v1.impl.clj-to-java :as clj2java]
             [clojure.string :as string]
+            [clojisr.v1.help :as help]
             [clojisr.v1.util :refer [bracket-data maybe-wrap-backtick]]
             [clojisr.v1.require :refer [require-r-package]]
-            [clojisr.v1.engines :refer [engines]])
+            [clojisr.v1.engines :refer [engines]]
+            [clojisr.v1.robject :as robject])
   (:import clojisr.v1.robject.RObject))
 
 (defn init [& {:keys [session-args]}]
@@ -206,16 +208,10 @@
 (defn help
   "Gets help for an R object or function"
   ([r-object]
-   (let [symbol (second  (re-find #"\{(.*)\}" (:code r-object)))
-         split (string/split symbol #"::")]
-
-     (help (second split) (first split))))
+   (help/help r-object (session/fetch nil)))
 
   ([function package]
-   (->>
-    (r (format  "capture.output(tools:::Rd2txt(utils:::.getHelpFile(as.character(help(%s,%s))), options=list(underline_titles=FALSE)))" (name function) (name package)))
-    r->clj
-    (string/join "\n"))))
+   (help/help function package (session/fetch nil))))
 
 
 (defn print-help

src/clojisr/v1/require.clj

@@ -1,13 +1,22 @@
 (ns clojisr.v1.require
-  (:require [clojisr.v1.session :as session]
-            [clojisr.v1.using-sessions :as using-sessions]
-            [clojisr.v1.eval :as evl]
-            [clojisr.v1.protocols :as prot]
-            [clojisr.v1.known-classes :as known-classes]
-            [clojisr.v1.util :as util :refer [clojurize-r-symbol exception-cause]]
-            [clojisr.v1.impl.common :refer [strange-symbol-name?]]
-            [clojisr.v1.impl.java-to-clj :refer [java->clj]]
-            [clojure.tools.logging.readable :as log]))
+  (:require
+   [clojisr.v1.eval :as evl]
+   [clojisr.v1.impl.common :refer [strange-symbol-name?]]
+   [clojisr.v1.impl.java-to-clj :refer [java->clj]]
+   [clojisr.v1.known-classes :as known-classes]
+   [clojisr.v1.protocols :as prot]
+   [clojisr.v1.session :as session]
+
+   [clojisr.v1.using-sessions :as using-sessions]
+   [clojisr.v1.util :refer [clojurize-r-symbol exception-cause if-assoc-meta]]
+
+   [clojisr.v1.help :as help]
+   [clojure.tools.logging.readable :as log]
+   [vrksasana.util :as util]
+   [clojisr.v1.robject :as robject]))
+
+
+(def attach-help-as-docstring-to-vars (atom false))
 
 (defn package-r-object [package-symbol object-symbol]
   (evl/r (format "{%s::`%s`}"
@@ -69,45 +78,57 @@
         (seq opt) (list ['& {:keys opt}])
         :else '([])))))
 
-(defn r-symbol->clj-symbol [r-symbol r-object]
-  (if-let [arglists (r-object->arglists r-object)]
-    (vary-meta r-symbol assoc :arglists arglists)
-    r-symbol))
 
-(defn add-to-ns [ns-symbol r-symbol r-object]
+(defn r-symbol->clj-symbol [session r-symbol r-object] 
+  (let [arglists (r-object->arglists r-object)]
+
+    (cond-> r-symbol
+      arglists (vary-meta 
+                 assoc
+                 :arglists arglists)
+
+
+      @attach-help-as-docstring-to-vars
+      (if-assoc-meta :doc (do 
+                                 (println :attach-help r-symbol)
+                                 (help/help r-object session))))))
+
+(defn add-to-ns [session ns-symbol r-symbol r-object]
   (intern ns-symbol
-          (r-symbol->clj-symbol r-symbol r-object)
+          (r-symbol->clj-symbol session r-symbol r-object)
           r-object))
 
-(defn symbols->add-to-ns [ns-symbol r-symbols]
+(defn symbols->add-to-ns [session ns-symbol r-symbols]
   (doseq [[r-symbol r-object] r-symbols]
-    (add-to-ns ns-symbol r-symbol r-object)))
+    (add-to-ns session ns-symbol r-symbol r-object)))
 
 (defn require-r-package [[package-symbol & {:keys [as refer]}]]
   (try
     (let [session (session/fetch-or-make nil)]
-      (evl/eval-form `(library ~package-symbol) session))
-    (let [r-ns-symbol (->> package-symbol
-                           (str "r.")
-                           symbol)
-          r-symbols (all-r-symbols-map package-symbol)]
+      (evl/eval-form `(library ~package-symbol) session)
+      (let [r-ns-symbol (->> package-symbol
+                             (str "r.")
+                             symbol)
+            r-symbols (all-r-symbols-map package-symbol)]
 
       ;; r.package namespace
-      (find-or-create-ns r-ns-symbol)
-      (symbols->add-to-ns r-ns-symbol r-symbols)
+        (find-or-create-ns r-ns-symbol)
+        (symbols->add-to-ns session r-ns-symbol r-symbols)
 
       ;; alias namespaces
       ;; https://clojurians.zulipchat.com/#narrow/stream/224816-clojisr-dev/topic/require-r.20vs.20-require-python
-      (alias package-symbol r-ns-symbol)
-      (when as (alias as r-ns-symbol))
+        (alias package-symbol r-ns-symbol)
+        (when as (alias as r-ns-symbol))
 
       ;; inject symbol into current namespace
-      (when refer
-        (let [this-ns-symbol (-> *ns* str symbol)]
-          (symbols->add-to-ns this-ns-symbol
-                              (if (= refer :all)
-                                r-symbols
-                                (select-keys r-symbols refer))))))
+        (when refer
+          (let [this-ns-symbol (-> *ns* str symbol)]
+            (symbols->add-to-ns
+             session
+             this-ns-symbol
+             (if (= refer :all)
+               r-symbols
+               (select-keys r-symbols refer)))))))
     (catch Exception e
       (log/warn [::require-r-package {:package-symbol package-symbol
                                       :cause (exception-cause e)}])

src/clojisr/v1/util.clj

@@ -96,6 +96,14 @@
         (recur threaded (next forms)))
       x)))
 
+
+(defn if-assoc-meta 
+  "If value non-nil, assoc it to meta with key"
+  [s k v]
+  (if ( some? v)
+    (vary-meta s assoc k v)
+    s))
+
 (comment
   (-|> 4
        :+

test/clojisr/v1/help_test.clj

@@ -0,0 +1,29 @@
+(ns clojisr.v1.help-test
+  (:require 
+   [clojure.string :as str] 
+   [clojure.test :refer [is deftest]]
+   [clojisr.v1.r  :as r]))
+
+
+(r/require-r '[randomForest])
+
+(deftest help-with-doctrsing
+  (reset! clojisr.v1.require/attach-help-as-docstring-to-vars true)
+  (r/require-r '[randomForest])
+  (is (str/starts-with? 
+       (:doc (meta (var r.randomForest/randomForest)))
+       "Classification and Regression with Random Forest")))
+
+
+(deftest help-without-doctrsing
+  (reset! clojisr.v1.require/attach-help-as-docstring-to-vars false)
+  (r/require-r '[randomForest])
+  (is (nil?
+       (:doc (meta (var r.randomForest/randomForest))))
+      ))
+
+(deftest help-function 
+  (is (str/starts-with? 
+       (r/help "randomForest" "randomForest")
+       "Classification and Regression with Random Forest"
+                        )))