Fix editor apidocs generation (defold#9471)

* Docs

* Doc

* java

editor/project.clj

@@ -179,7 +179,19 @@
                       :preflight {:dependencies [[jonase/kibit "0.1.6" :exclusions [org.clojure/clojure]]
                                                  [cljfmt-mg "0.6.4" :exclusions [org.clojure/clojure]]]}
                       :sidecar {:source-paths ["sidecar"]}
-                      :docs {:source-paths ["src/docs"]}
+                      :docs {:source-paths ["src/docs"]
+                             ;; Docs are generated by the engine build scripts at a point BEFORE
+                             ;; the bob is even built, so we need a separate "project" without bob
+                             ;; dependency to generate docs
+                             :java-source-paths ^:replace []
+                             :dependencies ^:replace [[org.clojure/clojure "1.10.0"]
+                                                      [commons-io/commons-io "2.4"]
+                                                      [prismatic/schema "1.1.9"]
+                                                      [org.luaj/luaj-jse "3.0.1"]
+                                                      [clj-antlr "0.2.2"
+                                                       :exclusions [org.antlr/antlr4 org.antlr/antlr4-runtime]]
+                                                      [org.antlr/antlr4 "4.7.2"]
+                                                      [org.antlr/antlr4-runtime "4.7.2"]]}
                       :uberjar {:prep-tasks  ^:replace []
                                 :aot          :all
                                 :auto-clean   false

editor/scripts/bundle.py

@@ -631,7 +631,7 @@ def create_installer(options):
   build                 Build editor
   bundle                Create editor bundle (zip) from built files
   sign                  Sign editor bundle (zip)
-  docs                  Produce docs (editor_doc.json, editor_doc.sdoc)
+  docs                  Produce docs (editor.apidoc)
   installer             Create editor installer from bundle (zip)'''
 
     parser = optparse.OptionParser(usage)

editor/src/clj/editor/adb.clj

@@ -15,15 +15,15 @@
 (ns editor.adb
   (:require [clojure.string :as string]
             [editor.fs :as fs]
+            [editor.os :as os]
             [editor.prefs :as prefs]
-            [editor.process :as process]
-            [editor.util :as util]))
+            [editor.process :as process]))
 
 (defmacro attempt [expr]
   `(try ~expr (catch Exception _#)))
 
 (defn- infer-adb-location! []
-  (case (util/os)
+  (case (os/os)
     :macos (or
              (some-> (fs/evaluate-path "$ANDROID_HOME/platform-tools/adb") fs/existing-path)
              (some-> (attempt (process/exec! "which" "adb")) fs/existing-path)

editor/src/clj/editor/app_view.clj

@@ -55,6 +55,7 @@
             [editor.live-update-settings :as live-update-settings]
             [editor.lsp :as lsp]
             [editor.lua :as lua]
+            [editor.os :as os]
             [editor.pipeline :as pipeline]
             [editor.pipeline.bob :as bob]
             [editor.prefs :as prefs]
@@ -76,7 +77,6 @@
             [editor.types :as types]
             [editor.ui :as ui]
             [editor.url :as url]
-            [editor.util :as util]
             [editor.view :as view]
             [editor.workspace :as workspace]
             [internal.graph.types :as gt]
@@ -86,14 +86,13 @@
             [util.http-server :as http-server]
             [util.profiler :as profiler]
             [util.thread-util :as thread-util])
-  (:import [clojure.lang ExceptionInfo]
-           [com.defold.editor Editor]
+  (:import [com.defold.editor Editor]
            [com.defold.editor UIUtil]
            [com.dynamo.bob Platform]
            [com.dynamo.bob.bundle BundleHelper]
            [com.sun.javafx PlatformUtil]
            [com.sun.javafx.scene NodeHelper]
-           [java.io BufferedReader File IOException OutputStream PipedInputStream PipedOutputStream PrintWriter]
+           [java.io File OutputStream PipedInputStream PipedOutputStream PrintWriter]
            [java.net URL]
            [java.nio.charset StandardCharsets]
            [java.util Collection List]
@@ -2783,7 +2782,7 @@ If you do not specifically require different script states, consider changing th
 
 (def ^:private xdg-desktop-menu-path
   (delay
-    (when (util/is-linux?)
+    (when (os/is-linux?)
       (try
         (process/exec! "which" "xdg-desktop-menu")
         (catch Throwable _)))))

editor/src/clj/editor/boot_open_project.clj

@@ -37,6 +37,7 @@
             [editor.html-view :as html-view]
             [editor.icons :as icons]
             [editor.notifications-view :as notifications-view]
+            [editor.os :as os]
             [editor.outline-view :as outline-view]
             [editor.pipeline.bob :as bob]
             [editor.properties-view :as properties-view]
@@ -51,7 +52,6 @@
             [editor.targets :as targets]
             [editor.ui :as ui]
             [editor.ui.updater :as ui.updater]
-            [editor.util :as util]
             [editor.web-profiler :as web-profiler]
             [editor.workspace :as workspace]
             [service.log :as log]
@@ -216,7 +216,7 @@
           (init-pending-update-indicator! stage update-link project changes-view updater)))
 
       ;; The menu-bar-space element should only be present if the menu-bar element is not.
-      (let [collapse-menu-bar? (and (util/is-mac-os?)
+      (let [collapse-menu-bar? (and (os/is-mac-os?)
                                     (.isUseSystemMenuBar menu-bar))]
         (.setVisible menu-bar-space collapse-menu-bar?)
         (.setManaged menu-bar-space collapse-menu-bar?))

editor/src/clj/editor/code/view.clj

@@ -42,6 +42,7 @@
             [editor.lsp :as lsp]
             [editor.markdown :as markdown]
             [editor.notifications :as notifications]
+            [editor.os :as os]
             [editor.prefs :as prefs]
             [editor.resource :as resource]
             [editor.resource-node :as resource-node]
@@ -50,7 +51,6 @@
             [editor.ui.bindings :as b]
             [editor.ui.fuzzy-choices :as fuzzy-choices]
             [editor.ui.fuzzy-choices-popup :as popup]
-            [editor.util :as eutil]
             [editor.view :as view]
             [editor.workspace :as workspace]
             [internal.util :as util]
@@ -3308,7 +3308,7 @@
       (insert-text! view-node ({"≃" "~="} x x)))))
 
 (defn- setup-input-method-requests! [^Canvas canvas view-node]
-  (when (eutil/is-linux?)
+  (when (os/is-linux?)
     (doto canvas
       (.setInputMethodRequests
         (reify InputMethodRequests

editor/src/clj/editor/defold_project.clj

@@ -30,6 +30,7 @@
             [editor.handler :as handler]
             [editor.library :as library]
             [editor.lsp :as lsp]
+            [editor.os :as os]
             [editor.placeholder-resource :as placeholder-resource]
             [editor.progress :as progress]
             [editor.resource :as resource]
@@ -38,7 +39,6 @@
             [editor.resource-update :as resource-update]
             [editor.settings-core :as settings-core]
             [editor.ui :as ui]
-            [editor.util :as util]
             [editor.workspace :as workspace]
             [internal.java :as java]
             [internal.util :as iutil]
@@ -643,7 +643,7 @@
 
 (def ^:private bundle-targets
   (into []
-        (concat (when (util/is-mac-os?) [[:ios "iOS Application..."]]) ; macOS is required to sign iOS ipa.
+        (concat (when (os/is-mac-os?) [[:ios "iOS Application..."]]) ; macOS is required to sign iOS ipa.
                 [[:android "Android Application..."]
                  [:macos   "macOS Application..."]
                  [:windows "Windows Application..."]

editor/src/clj/editor/dialogs.clj

@@ -35,9 +35,9 @@
             [editor.fxui :as fxui]
             [editor.github :as github]
             [editor.handler :as handler]
+            [editor.os :as os]
             [editor.progress :as progress]
             [editor.ui :as ui]
-            [editor.util :as util]
             [service.log :as log])
   (:import [clojure.lang Named]
            [java.io File]
@@ -48,7 +48,7 @@
            [javafx.event Event]
            [javafx.scene Node]
            [javafx.scene.control ListView TextField]
-           [javafx.scene.input KeyCode KeyEvent MouseEvent MouseButton]
+           [javafx.scene.input KeyCode KeyEvent MouseButton MouseEvent]
            [javafx.stage DirectoryChooser FileChooser FileChooser$ExtensionFilter Stage Window]
            [org.apache.commons.io FilenameUtils]))
 
@@ -455,7 +455,7 @@
                     :variant :header
                     :text "This is a very common issue. See if any of these instructions help:"}]
                   (cond->
-                    (util/is-linux?)
+                    (os/is-linux?)
                     (conj {:fx/type fx.hyperlink/lifecycle
                            :text "OpenGL on linux"
                            :on-action (fn [_] (ui/open-url "https://defold.com/faq/faq/#linux-questions"))}))

editor/src/clj/editor/editor_extensions.clj

@@ -35,10 +35,10 @@
             [editor.handler :as handler]
             [editor.lsp :as lsp]
             [editor.lsp.async :as lsp.async]
+            [editor.os :as os]
             [editor.process :as process]
             [editor.resource :as resource]
             [editor.system :as system]
-            [editor.util :as util]
             [editor.workspace :as workspace])
   (:import [com.dynamo.bob Platform]
            [java.nio.file FileAlreadyExistsException Files NotDirectoryException Path]
@@ -342,7 +342,7 @@
   (let [lua-lsp-root (str (system/defold-unpack-path) "/" (.getPair (Platform/getHostPlatform)) "/bin/lsp/lua")]
     #{{:languages #{"lua"}
        :watched-files [{:pattern "**/.luacheckrc"}]
-       :launcher {:command [(str lua-lsp-root "/bin/lua-language-server" (when (util/is-win32?) ".exe"))
+       :launcher {:command [(str lua-lsp-root "/bin/lua-language-server" (when (os/is-win32?) ".exe"))
                             (str "--configpath=" lua-lsp-root "/config.json")]}}}))
 
 (def language-servers-coercer

editor/src/clj/editor/editor_extensions/docs.clj

@@ -15,9 +15,7 @@
 (ns editor.editor-extensions.docs
   (:require [clojure.string :as string]
             [editor.editor-extensions.ui-docs :as ui-docs]
-            [editor.lua-completion :as lua-completion]
-            [editor.system :as system]))
-
+            [editor.lua-completion :as lua-completion]))
 
 (defn editor-script-docs
   "Returns reducible with script doc maps covering the editor API"
@@ -183,7 +181,7 @@
          :description "Create a set transaction step.\n\nWhen the step is transacted using `editor.transact()`, it will set the node's property to a supplied value"}
         {:name "editor.version"
          :type :variable
-         :description (format "A string, version name of Defold.\n\ne.g. `\"%s\"`" (system/defold-version))}
+         :description "A string, version name of Defold"}
         {:name "editor.engine_sha1"
          :type :variable
          :description "A string, SHA1 of Defold engine"}

editor/src/clj/editor/fxui.clj

@@ -31,18 +31,18 @@
             [cljfx.mutator :as fx.mutator]
             [cljfx.prop :as fx.prop]
             [editor.error-reporting :as error-reporting]
-            [editor.ui :as ui]
-            [editor.util :as eutil])
+            [editor.os :as os]
+            [editor.ui :as ui])
   (:import [clojure.lang MultiFn]
            [com.defold.control ListCell]
            [java.util Collection]
            [javafx.application Platform]
+           [javafx.beans.property ReadOnlyProperty]
+           [javafx.beans.value ChangeListener]
            [javafx.collections ObservableList]
            [javafx.event Event]
            [javafx.scene Node]
-           [javafx.beans.property ReadOnlyProperty]
-           [javafx.beans.value ChangeListener]
-           [javafx.scene.control TextInputControl ListView ScrollPane]
+           [javafx.scene.control ListView ScrollPane TextInputControl]
            [javafx.stage Popup Window]
            [javafx.util Callback]))
 
@@ -398,7 +398,7 @@
   (assoc props
     :fx/type fx.stage/lifecycle
     :on-focused-changed ui/focus-change-listener
-    :icons (if (eutil/is-mac-os?) [] [ui/application-icon-image])))
+    :icons (if (os/is-mac-os?) [] [ui/application-icon-image])))
 
 (defn dialog-stage
   "Generic dialog `:stage` that mirrors behavior of `editor.ui/make-dialog-stage`"

editor/src/clj/editor/ios_deploy.clj

@@ -13,12 +13,12 @@
 ;; specific language governing permissions and limitations under the License.
 
 (ns editor.ios-deploy
-  (:require [editor.util :as util]
-            [editor.process :as process]
-            [clojure.data.json :as json]
+  (:require [clojure.data.json :as json]
             [clojure.java.io :as io]
             [editor.fs :as fs]
-            [editor.prefs :as prefs])
+            [editor.os :as os]
+            [editor.prefs :as prefs]
+            [editor.process :as process])
   (:import [clojure.lang IReduceInit]))
 
 (defn get-ios-deploy-path
@@ -30,7 +30,7 @@
     (or (fs/existing-path prefs-path)
         (throw (ex-info (format "ios-deploy path defined in preferences does not exist: '%s'" prefs-path)
                         {:path prefs-path})))
-    (if (= :macos (util/os))
+    (if (= :macos (os/os))
       (or
         (try (fs/existing-path (process/exec! "which" "ios-deploy")) (catch Exception _))
         (fs/existing-path "/opt/homebrew/bin/ios-deploy")

editor/src/clj/editor/keymap.clj

@@ -13,8 +13,8 @@
 ;; specific language governing permissions and limitations under the License.
 
 (ns editor.keymap
-  (:require [editor.ui :as ui]
-            [editor.util :as util]
+  (:require [editor.os :as os]
+            [editor.ui :as ui]
             [util.fn :as fn])
   (:import [javafx.scene Scene]
            [javafx.scene.input KeyCharacterCombination KeyCodeCombination KeyCombination KeyCombination$ModifierValue KeyEvent]))
@@ -385,7 +385,7 @@
            ["Z" :rotate-brush-90-degrees]]})
 
 (def default-host-key-bindings
-  (platform->default-key-bindings (util/os)))
+  (platform->default-key-bindings (os/os)))
 
 (def ^:private default-allowed-duplicate-shortcuts
   #{"Alt+Down"
@@ -518,7 +518,7 @@
 
 (defn typable?
   ([key-combo-data]
-   (typable? key-combo-data (util/os)))
+   (typable? key-combo-data (os/os)))
   ([{:keys [alt-down? control-down? meta-down?]} os]
    (let [mac? (= os :macos)]
      (-> typable-truth-table
@@ -595,7 +595,7 @@
                          allowed-duplicate-shortcuts
                          allowed-typable-shortcuts]
                   :or   {valid-command? fn/constantly-true
-                         platform (util/os)
+                         platform (os/os)
                          throw-on-error? false
                          allowed-duplicate-shortcuts default-allowed-duplicate-shortcuts
                          allowed-typable-shortcuts default-allowed-typable-shortcuts}}]

editor/src/clj/editor/lsp/server.clj

@@ -18,14 +18,14 @@
             [clojure.spec.alpha :as s]
             [clojure.string :as string]
             [dynamo.graph :as g]
+            [editor.code-completion :as code-completion]
             [editor.code.data :as data]
             [editor.lsp.async :as lsp.async]
-            [editor.code-completion :as code-completion]
             [editor.lsp.base :as lsp.base]
             [editor.lsp.jsonrpc :as lsp.jsonrpc]
             [editor.lua :as lua]
+            [editor.os :as os]
             [editor.resource :as resource]
-            [editor.util :as util]
             [editor.workspace :as workspace]
             [service.log :as log])
   (:import [editor.code.data Cursor CursorRange]
@@ -110,7 +110,7 @@
   (->RawRequest notification result-converter))
 
 (defn- make-uri-string [abs-path]
-  (let [path (if (util/is-win32?)
+  (let [path (if (os/is-win32?)
                (str "/" (string/replace abs-path "\\" "/"))
                abs-path)]
     (str (URI. "file" "" path nil))))

editor/src/clj/editor/os.clj

@@ -0,0 +1,32 @@
+;; Copyright 2020-2024 The Defold Foundation
+;; Copyright 2014-2020 King
+;; Copyright 2009-2014 Ragnar Svensson, Christian Murray
+;; Licensed under the Defold License version 1.0 (the "License"); you may not use
+;; this file except in compliance with the License.
+;;
+;; You may obtain a copy of the License, together with FAQs at
+;; https://www.defold.com/license
+;;
+;; Unless required by applicable law or agreed to in writing, software distributed
+;; under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+;; CONDITIONS OF ANY KIND, either express or implied. See the License for the
+;; specific language governing permissions and limitations under the License.
+
+(ns editor.os
+  (:import [com.dynamo.bob Platform]))
+
+(defn- os-raw []
+  (keyword (.. Platform getHostPlatform getOs)))
+
+(def ^{:arglists '([])} os
+  "Returns either :win32, :macos or :linux"
+  (memoize os-raw))
+
+(defn is-mac-os? []
+  (= (os) :macos))
+
+(defn is-linux? []
+  (= (os) :linux))
+
+(defn is-win32? []
+  (= (os) :win32))