Add ns docstrings for most ns in src/main

- Added to CI now that it passes
- Added no-doc for docstrings that don't add any more than what's in the
ns name or for ones where I didn't know the ns that well

.clj-kondo/config.edn

@@ -22,25 +22,52 @@
   {:aliases {datascript.core d
              datascript.transit dt
              datascript.db ddb
-             lambdaisland.glogi log
-             medley.core medley
+             electron.ipc ipc
+             frontend.commands commands
+             frontend.config config
+             frontend.date date
+             frontend.db db
+             frontend.db-mixins db-mixins
              frontend.db.query-dsl query-dsl
              frontend.db.react react
              frontend.db.query-react query-react
-             frontend.util util
-             frontend.util.property property
-             frontend.util.text text-util
-             frontend.config config
+             frontend.diff diff
+             frontend.encrypt encrypt
              frontend.format.mldoc mldoc
              frontend.format.block block
+             frontend.fs fs
+             frontend.fs.bfs bfs
+             frontend.fs.capacitor-fs capacitor-fs
+             frontend.fs.nfs nfs
              frontend.handler.extract extract
              frontend.handler.common common-handler
              frontend.handler.common.file file-common-handler
              frontend.handler.config config-handler
+             frontend.handler.events events
              frontend.handler.global-config global-config-handler
+             frontend.handler.ui ui-handler
+             frontend.handler.notification notification
+             frontend.handler.page page-handler
+             frontend.handler.repo repo-handler
              frontend.handler.repo-config repo-config-handler
+             frontend.handler.search search-handler
+             frontend.idb idb
+             frontend.loader loader
+             frontend.mixins mixins
              frontend.mobile.util mobile-util
+             frontend.page page
+             frontend.search search
              frontend.state state
+             frontend.template template
+             frontend.ui ui
+             frontend.util util
+             frontend.util.clock clock
+             frontend.util.property property
+             frontend.util.persist-var persist-var
+             frontend.util.text text-util
+             frontend.util.url url-util
+             frontend.util.thingatpt thingatpt
+             lambdaisland.glogi log
              logseq.graph-parser graph-parser
              logseq.graph-parser.text text
              logseq.graph-parser.block gp-block
@@ -50,7 +77,8 @@
              logseq.graph-parser.config gp-config
              logseq.graph-parser.util.page-ref page-ref
              logseq.graph-parser.util.block-ref block-ref
-             logseq.graph-parser.date-time-util date-time-util}}
+             logseq.graph-parser.date-time-util date-time-util
+             medley.core medley}}
 
   :namespace-name-mismatch {:level :warning}
   :used-underscored-binding {:level :warning}}

.github/workflows/build.yml

@@ -106,6 +106,9 @@ jobs:
       - name: Lint for vars that are too large
         run: bb lint:large-vars
 
+      - name: Lint for namespaces that aren't documented
+        run: bb lint:ns-docstrings
+
       - name: Lint invalid translation entries
         run: bb lang:invalid-translations
 

bb.edn

@@ -6,7 +6,7 @@
   logseq/bb-tasks
   #_{:local/root "../bb-tasks"}
   {:git/url "https://github.com/logseq/bb-tasks"
-   :git/sha "abb32ccd26405d56fd28a29d56f3cb902b8c4334"}
+   :git/sha "95e4fbdb7bbf1c720c6f8b58e3b3b96b3b487526"}
   logseq/graph-parser
   {:local/root "deps/graph-parser"}
   org.clj-commons/digest
@@ -70,6 +70,9 @@
   lint:carve
   logseq.bb-tasks.lint.carve/-main
 
+  lint:ns-docstrings
+  logseq.bb-tasks.lint.ns-docstrings/-main
+
   nbb:watch
   logseq.bb-tasks.nbb.watch/watch
 
@@ -98,4 +101,10 @@
    ;; TODO: Address vars tagged with cleanup-todo. These
    ;; are left mostly because they are not high priority
    ;; or not well understood
-   :metadata-exceptions #{:large-vars/cleanup-todo}}}}
+   :metadata-exceptions #{:large-vars/cleanup-todo}}
+
+  :ns-docstrings
+  {:paths ["src/main"]
+   ;; Ignore namespaces that won't be helpful to document initially
+   ;; e.g. frontend.components.onboarding -> "Onboarding fns"
+   :ignore-regex "^(frontend.components|frontend.extensions|frontend.modules|frontend.mobile)"}}}

docs/dev-practices.md

@@ -54,11 +54,13 @@ To configure the linter, see the `[:tasks/config :large-vars]` path of bb.edn.
 
 ### Document namespaces
 
-Documentation helps teams share their knowledge and enables more individuals to contribute to the codebase. Documenting our namespaces is a good first step to improving our documentation. Currently this linter is only run on our deps/. To run this linter:
+Documentation helps teams share their knowledge and enables more individuals to contribute to the codebase. Documenting our namespaces is a good first step to improving our documentation. To run this linter:
 ```
 bb lint:ns-docstrings
 ```
 
+To skip documenting a ns, use the common `^:no-doc` metadata flag.
+
 ### Datalog linting
 
 We use [datascript](https://github.com/tonsky/datascript)'s datalog to power our

scripts/src/logseq/tasks/dev.clj

@@ -13,6 +13,7 @@
   (doseq [cmd ["clojure -M:clj-kondo --parallel --lint src --cache false"
                "bb lint:carve"
                "bb lint:large-vars"
-               "bb lang:invalid-translations"]]
+               "bb lang:invalid-translations"
+               "bb lint:ns-docstrings"]]
     (println cmd)
     (shell cmd)))

src/main/electron/ipc.cljs

@@ -1,4 +1,5 @@
 (ns electron.ipc
+  "Provides fns to send ipc messages to electron's main process"
   (:require [cljs-bean.core :as bean]
             [promesa.core :as p]
             [frontend.util :as util]))

src/main/electron/listener.cljs

@@ -1,4 +1,6 @@
 (ns electron.listener
+  "System-component-like ns that defines listeners by event name to receive ipc
+  messages from electron's main process"
   (:require [frontend.state :as state]
             [frontend.context.i18n :refer [t]]
             [frontend.date :as date]

src/main/frontend/commands.cljs

@@ -1,4 +1,5 @@
 (ns frontend.commands
+  "Provides functionality for commands and advanced commands"
   (:require [clojure.string :as string]
             [frontend.config :as config]
             [frontend.date :as date]

src/main/frontend/components/file_sync.cljs

@@ -13,7 +13,7 @@
             [frontend.fs :as fs]
             [frontend.fs.sync :as fs-sync]
             [frontend.handler.file-sync :refer [*beta-unavailable?] :as file-sync-handler]
-            [frontend.handler.notification :as notifications]
+            [frontend.handler.notification :as notification]
             [frontend.handler.page :as page-handler]
             [frontend.handler.repo :as repo-handler]
             [frontend.handler.user :as user-handler]
@@ -61,7 +61,7 @@
                                  :else
                                  nil)
                                (.then #(do
-                                         (notifications/show! (str "Cloned to => " dest-dir) :success)
+                                         (notification/show! (str "Cloned to => " dest-dir) :success)
                                          (web-nfs/ls-dir-files-with-path! dest-dir)
                                          (repo-handler/remove-repo! {:url repo})
                                          (close-fn)))

src/main/frontend/components/repo.cljs

@@ -18,7 +18,7 @@
             [electron.ipc :as ipc]
             [goog.object :as gobj]
             [frontend.components.encryption :as encryption]
-            [frontend.encrypt :as e]
+            [frontend.encrypt :as encrypt]
             [cljs.core.async :as async :refer [go <!]]
             [frontend.handler.file-sync :as file-sync]
             [reitit.frontend.easy :as rfe]))
@@ -60,7 +60,7 @@
                                      (state/pub-event! [:graph/switch url])))
 
      [:div.controls
-      (when (e/encrypted-db? url)
+      (when (encrypt/encrypted-db? url)
         [:a.control {:title    "Show encryption information about this graph"
                      :on-click (fn []
                                  (if remote?

src/main/frontend/config.cljs

@@ -1,4 +1,5 @@
 (ns frontend.config
+  "App config and fns built on top of configuration"
   (:require [clojure.set :as set]
             [clojure.string :as string]
             [frontend.mobile.util :as mobile-util]

src/main/frontend/core.cljs

@@ -1,4 +1,5 @@
 (ns frontend.core
+  "Entry ns for the mobile, browser and electron frontend apps"
   (:require [rum.core :as rum]
             [frontend.handler :as handler]
             [frontend.handler.plugin :as plugin-handler]

src/main/frontend/date.cljs

@@ -1,4 +1,5 @@
 (ns frontend.date
+  "Date related utility fns"
   (:require ["chrono-node" :as chrono]
             [cljs-bean.core :as bean]
             [cljs-time.coerce :as tc]

src/main/frontend/db.cljs

@@ -1,4 +1,5 @@
 (ns frontend.db
+  "Main entry ns for db related fns"
   (:require [clojure.core.async :as async]
             [datascript.core :as d]
             [logseq.db.schema :as db-schema]

src/main/frontend/db/debug.cljs

@@ -1,4 +1,4 @@
-(ns frontend.db.debug
+(ns ^:no-doc frontend.db.debug
   (:require [frontend.db.utils :as db-utils]
             [frontend.db :as db]
             [datascript.core :as d]

src/main/frontend/db/migrate.cljs

@@ -1,4 +1,4 @@
-(ns frontend.db.migrate
+(ns ^:no-doc frontend.db.migrate
   (:require [datascript.core :as d]))
 
 (defn get-collapsed-blocks

src/main/frontend/db/outliner.cljs

@@ -1,4 +1,5 @@
 (ns frontend.db.outliner
+  "Db related fns for the outliner module"
   (:require [datascript.core :as d]))
 
 (defn get-by-id

src/main/frontend/db/persist.cljs

@@ -1,4 +1,5 @@
 (ns frontend.db.persist
+  "Handles operations to persisting db to disk or indexedDB"
   (:require [frontend.util :as util]
             [frontend.idb :as idb]
             [frontend.config :as config]

src/main/frontend/db_mixins.cljs

@@ -1,4 +1,5 @@
 (ns frontend.db-mixins
+  "Rum mixins that depend on db"
   (:require [frontend.db.react :as react]))
 
 (def query

src/main/frontend/debug.clj

@@ -1,4 +1,5 @@
 (ns frontend.debug
+  "Macros that are useful for debugging"
   (:refer-clojure :rename {defn core-defn}))
 
 (defmacro defn [name & fdecl]

src/main/frontend/debug.cljs

@@ -1,4 +1,5 @@
 (ns frontend.debug
+  "Fns that are useful for debugging"
   (:require [cljs.pprint :as pprint]
             [frontend.state :as state]))
 

src/main/frontend/diff.cljs

@@ -1,4 +1,4 @@
-(ns frontend.diff
+(ns ^:no-doc frontend.diff
   (:require [clojure.string :as string]
             ["diff" :as jsdiff]
             [goog.object :as gobj]

src/main/frontend/encrypt.cljs

@@ -1,4 +1,5 @@
 (ns frontend.encrypt
+  "Encryption related fns for use with encryption feature and file sync"
   (:require [logseq.graph-parser.utf8 :as utf8]
             [frontend.db.utils :as db-utils]
             [frontend.util :as util]

src/main/frontend/error.cljs

@@ -1,4 +1,5 @@
 (ns frontend.error
+  "Error related utility fns"
   (:require [clojure.string :as string]))
 
 (def ignored

src/main/frontend/extensions/pdf/utils.cljs

@@ -3,7 +3,7 @@
             [cljs-bean.core :as bean]
             [frontend.util :as util]
             ["/frontend/extensions/pdf/utils" :as js-utils]
-            [frontend.db :as front-db]
+            [frontend.db :as db]
             [frontend.loader :refer [load]]
             [clojure.string :as string]))
 
@@ -115,7 +115,7 @@
     (mapv #(if (map? %) % (bean/->clj %)) its)))
 
 (defn gen-uuid []
-  (front-db/new-block-id))
+  (db/new-block-id))
 
 (defn js-load$
   [url]
@@ -186,4 +186,4 @@
  (fix-selection-text-breakline "he is 1\n8 years old")
  (fix-selection-text-breakline "这是一个\n\n段落")
  (fix-selection-text-breakline "これ\n\nは、段落")
- (fix-selection-text-breakline "this is a te-\nst paragraph"))
+ (fix-selection-text-breakline "this is a te-\nst paragraph"))

src/main/frontend/external.cljs

@@ -1,4 +1,5 @@
 (ns frontend.external
+  "Handles importing from external services"
   (:require [frontend.external.roam :refer [->Roam]]
             [frontend.external.protocol :as protocol]))
 

src/main/frontend/external/protocol.cljc

@@ -1,4 +1,4 @@
-(ns frontend.external.protocol)
+(ns ^:no-doc frontend.external.protocol)
 
 (defprotocol External
   (toMarkdownFiles [this content config]
@@ -7,4 +7,3 @@
   ;; Long-term goal:
   ;; (toMldocAst [this content])
   ;; (fromMldocAst [this ast])
-

src/main/frontend/external/roam.cljs

@@ -1,4 +1,5 @@
 (ns frontend.external.roam
+  "Provides roam import by implementing the external protocol"
   (:require [cljs-bean.core :as bean]
             [frontend.external.protocol :as protocol]
             [frontend.date :as date]

src/main/frontend/external/roam_export.cljs

@@ -1,4 +1,4 @@
-(ns frontend.external.roam-export
+(ns ^:no-doc frontend.external.roam-export
   (:require [clojure.set :as s]
             [clojure.string :as str]
             [clojure.walk :as walk]

src/main/frontend/format.cljs

@@ -1,4 +1,6 @@
 (ns frontend.format
+  "Main ns for providing common operations on file content like conversion to html
+and edn. Can handle org, markdown and adoc formats"
   (:require [frontend.format.mldoc :refer [->MldocMode] :as mldoc]
             [frontend.format.adoc :refer [->AdocMode]]
             [frontend.format.protocol :as protocol]

src/main/frontend/format/adoc.cljs

@@ -1,4 +1,5 @@
 (ns frontend.format.adoc
+  "Partial implementation of format protocol for adoc that uses asciidoctor"
   (:require [frontend.format.protocol :as protocol]
             [frontend.loader :as loader]))
 

src/main/frontend/format/mldoc.cljs

@@ -1,5 +1,6 @@
 (ns frontend.format.mldoc
-  "Mldoc code needed by app but not graph-parser"
+  "Contains any mldoc code needed by app but not graph-parser. Implements format
+  protocol for org and and markdown formats"
   (:require [clojure.string :as string]
             [frontend.format.protocol :as protocol]
             [goog.object :as gobj]

src/main/frontend/format/protocol.cljs

@@ -1,4 +1,4 @@
-(ns frontend.format.protocol)
+(ns ^:no-doc frontend.format.protocol)
 
 (defprotocol Format
   (toEdn [this content config])

src/main/frontend/fs.cljs

@@ -1,9 +1,11 @@
 (ns frontend.fs
+  "System-component-like ns that provides common file operations for all
+  platforms by delegating to implementations of the fs protocol"
   (:require [cljs-bean.core :as bean]
             [frontend.config :as config]
             [frontend.fs.nfs :as nfs]
             [frontend.fs.node :as node]
-            [frontend.fs.capacitor-fs :as mobile]
+            [frontend.fs.capacitor-fs :as capacitor-fs]
             [frontend.fs.bfs :as bfs]
             [frontend.mobile.util :as mobile-util]
             [frontend.fs.protocol :as protocol]
@@ -18,7 +20,7 @@
 (defonce nfs-record (nfs/->Nfs))
 (defonce bfs-record (bfs/->Bfs))
 (defonce node-record (node/->Node))
-(defonce mobile-record (mobile/->Capacitorfs))
+(defonce mobile-record (capacitor-fs/->Capacitorfs))
 
 (defn local-db?
   [dir]

src/main/frontend/fs/bfs.cljs

@@ -1,4 +1,4 @@
-(ns frontend.fs.bfs
+(ns ^:no-doc frontend.fs.bfs
   (:require [frontend.fs.protocol :as protocol]
             [frontend.util :as util]
             [promesa.core :as p]))

src/main/frontend/fs/capacitor_fs.cljs

@@ -1,4 +1,5 @@
 (ns frontend.fs.capacitor-fs
+  "Implementation of fs protocol for mobile"
   (:require ["@capacitor/filesystem" :refer [Encoding Filesystem]]
             [cljs-bean.core :as bean]
             [clojure.string :as string]

src/main/frontend/fs/nfs.cljs

@@ -1,4 +1,4 @@
-(ns frontend.fs.nfs
+(ns ^:no-doc frontend.fs.nfs
   (:require [frontend.fs.protocol :as protocol]
             [frontend.util :as util]
             [clojure.string :as string]

src/main/frontend/fs/node.cljs

@@ -1,4 +1,5 @@
 (ns frontend.fs.node
+  "Implementation of fs protocol for desktop"
   (:require [clojure.string :as string]
             [electron.ipc :as ipc]
             [frontend.config :as config]

src/main/frontend/fs/protocol.cljs

@@ -1,4 +1,4 @@
-(ns frontend.fs.protocol
+(ns ^:no-doc frontend.fs.protocol
   ;; namespace local config to suppress 'new-path' of 'rename!'. clj-kondo's bug?
   {:clj-kondo/config {:linters {:private-call {:level :off}}}})
 

src/main/frontend/fs/sync.cljs

@@ -1,4 +1,5 @@
 (ns frontend.fs.sync
+  "Main ns for providing file sync functionality"
   (:require [cljs-http.client :as http]
             [cljs-time.core :as t]
             [cljs-time.format :as tf]

src/main/frontend/fs/watcher_handler.cljs

@@ -1,4 +1,5 @@
 (ns frontend.fs.watcher-handler
+  "Main ns that handles file watching events from electron's main process"
   (:require [clojure.string :as string]
             [frontend.config :as config]
             [frontend.db :as db]

src/main/frontend/handler.cljs

@@ -1,4 +1,6 @@
 (ns frontend.handler
+  "Main ns that handles application startup. Closest ns that we have to a
+  system. Contains a couple of small system components"
   (:require [cljs.reader :refer [read-string]]
             [clojure.string :as string]
             [electron.ipc :as ipc]

src/main/frontend/handler/block.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.block
+(ns ^:no-doc frontend.handler.block
   (:require
    [clojure.set :as set]
    [clojure.string :as string]

src/main/frontend/handler/command_palette.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.command-palette
+  "System-component-like ns for command palette's functionality"
   (:require [cljs.spec.alpha :as s]
             [frontend.modules.shortcut.data-helper :as shortcut-helper]
             [frontend.spec :as spec]

src/main/frontend/handler/common.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.common
+  "Common fns for handlers"
   (:require [cljs-bean.core :as bean]
             [cljs.reader :as reader]
             [clojure.string :as string]

src/main/frontend/handler/dnd.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.dnd
+  "Provides fns for drag n drop"
   (:require [frontend.handler.editor :as editor-handler]
             [frontend.modules.outliner.core :as outliner-core]
             [frontend.modules.outliner.tree :as tree]

src/main/frontend/handler/draw.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.draw
+  "Provides util handler fns for drawing"
   (:refer-clojure :exclude [load-file])
   (:require [frontend.config :as config]
             [frontend.date :as date]

src/main/frontend/handler/editor.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.editor
+(ns ^:no-doc frontend.handler.editor
   (:require ["path" :as path]
             [clojure.set :as set]
             [clojure.string :as string]
@@ -613,7 +613,7 @@
             (when edit-block?
               (if (and replace-empty-target?
                        (string/blank? (:block/content last-block)))
-                ;; 20ms of waiting for DOM to load the block, to avoid race condition. 
+                ;; 20ms of waiting for DOM to load the block, to avoid race condition.
                 ;; It's ensuring good response under M1 pro
                 ;; Used to be 10ms before, but is causing occasional failure on M1 pro with a full page of blocks,
                 ;; or failing E2E with a small number of blocks.

src/main/frontend/handler/editor/keyboards.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.editor.keyboards
+(ns ^:no-doc frontend.handler.editor.keyboards
   (:require [frontend.handler.editor :as editor-handler]
             [frontend.mixins :as mixins]
             [frontend.state :as state]

src/main/frontend/handler/editor/lifecycle.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.editor.lifecycle
+(ns ^:no-doc frontend.handler.editor.lifecycle
   (:require [frontend.handler.editor :as editor-handler :refer [get-state]]
             [frontend.handler.editor.keyboards :as keyboards-handler]
             [frontend.state :as state :refer [sub]]

src/main/frontend/handler/events.cljs

@@ -1,4 +1,7 @@
 (ns frontend.handler.events
+  "System-component-like ns that defines named events and listens on a
+  core.async channel to handle them. Any part of the system can dispatch
+  one of these events using state/pub-event!"
   (:refer-clojure :exclude [run!])
   (:require ["@capacitor/filesystem" :refer [Directory Filesystem]]
             [clojure.core.async :as async]
@@ -10,7 +13,7 @@
             [frontend.components.diff :as diff]
             [frontend.components.git :as git-component]
             [frontend.components.plugins :as plugin]
-            [frontend.components.search :as search]
+            [frontend.components.search :as component-search]
             [frontend.components.shell :as shell]
             [frontend.config :as config]
             [frontend.context.i18n :refer [t]]
@@ -43,7 +46,7 @@
             [frontend.modules.instrumentation.posthog :as posthog]
             [frontend.modules.outliner.file :as outliner-file]
             [frontend.modules.shortcut.core :as st]
-            [frontend.search :as search-db]
+            [frontend.search :as search]
             [frontend.state :as state]
             [frontend.ui :as ui]
             [frontend.util :as util]
@@ -330,7 +333,7 @@
     (state/set-modal! shell/shell)))
 
 (defmethod handle :go/search [_]
-  (state/set-modal! search/search-modal
+  (state/set-modal! component-search/search-modal
                     {:fullscreen? false
                      :close-btn?  false}))
 
@@ -453,7 +456,7 @@
               (try
                 (update-file-path deprecated-repo current-repo deprecated-app-id current-app-id)
                 (db-persist/delete-graph! deprecated-repo)
-                (search-db/remove-db! deprecated-repo)
+                (search/remove-db! deprecated-repo)
                 (state/delete-repo! {:url deprecated-repo})
                 (state/add-repo! {:url current-repo :nfs? true})
                 (catch :default e

src/main/frontend/handler/export.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.export
+(ns ^:no-doc frontend.handler.export
   (:require ["@capacitor/filesystem" :refer [Encoding Filesystem]]
             [cljs.pprint :as pprint]
             [clojure.set :as s]

src/main/frontend/handler/external.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.external
+  "Fns related to import from external services"
   (:require [clojure.edn :as edn]
             [clojure.walk :as walk]
             [frontend.external :as external]
@@ -14,7 +15,7 @@
             [logseq.graph-parser.mldoc :as gp-mldoc]
             [logseq.graph-parser.util :as gp-util]
             [logseq.graph-parser.date-time-util :as date-time-util]
-            [frontend.handler.page :as page]
+            [frontend.handler.page :as page-handler]
             [frontend.handler.editor :as editor]
             [frontend.handler.notification :as notification]
             [frontend.util :as util]
@@ -87,7 +88,7 @@
                          (mapv editor/wrap-parse-block))
           page-name (:title headers)]
       (when (not (db/page-exists? page-name))
-        (page/create! page-name {:redirect? false}))
+        (page-handler/create! page-name {:redirect? false}))
       (let [page-block (db/entity [:block/name (util/page-name-sanity-lc page-name)])
             children (:block/_parent page-block)
             blocks (db/sort-by-left children page-block)
@@ -115,13 +116,13 @@
   [{:keys [uuid title children] :as tree}]
   (let [has-children? (seq children)
         page-format (some-> tree (:children) (first) (:format))]
-    (try (page/create! title {:redirect?  false
-                              :format     page-format
-                              :uuid       uuid})
-         (catch :default e
-           (notification/show! (str "Error happens when creating page " title ":\n"
-                                    e
-                                    "\nSkipped and continue the remaining import.") :error)))
+    (try (page-handler/create! title {:redirect?  false
+                                      :format     page-format
+                                      :uuid       uuid})
+      (catch :default e
+        (notification/show! (str "Error happens when creating page " title ":\n"
+                                 e
+                                 "\nSkipped and continue the remaining import.") :error)))
     (when has-children?
       (let [page-block  (db/entity [:block/name (util/page-name-sanity-lc title)])
             first-child (first (:block/_left page-block)) ]

src/main/frontend/handler/file.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.file
+  "Provides util handler fns for files"
   (:refer-clojure :exclude [load-file])
   (:require [frontend.config :as config]
             [frontend.db :as db]

src/main/frontend/handler/file_sync.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.file-sync
+  "Provides util handler fns for file sync"
   (:require ["path" :as path]
             [cljs-time.format :as tf]
             [cljs.core.async :as async :refer [go <!]]

src/main/frontend/handler/graph.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.graph
+  "Provides util handler fns for graph view"
   (:require [clojure.set :as set]
             [clojure.string :as string]
             [frontend.db :as db]

src/main/frontend/handler/history.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.history
+(ns ^:no-doc frontend.handler.history
   (:require [frontend.db :as db]
             [frontend.handler.editor :as editor]
             [frontend.modules.editor.undo-redo :as undo-redo]

src/main/frontend/handler/image.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.image
+(ns ^:no-doc frontend.handler.image
   (:require [clojure.string :as string]
             [frontend.config :as config]
             [frontend.fs :as fs]

src/main/frontend/handler/journal.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.journal
+(ns ^:no-doc frontend.handler.journal
   (:require [frontend.date :as date]
             [frontend.handler.route :as route-handler]
             [frontend.state :as state]

src/main/frontend/handler/metadata.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.metadata
+  "System-component-like ns that manages writing to pages-metadata.edn"
   (:require [cljs.reader :as reader]
             [cljs.pprint]
             [clojure.string :as string]

src/main/frontend/handler/mobile/swipe.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.mobile.swipe
+(ns ^:no-doc frontend.handler.mobile.swipe
   (:require [cljs-bean.core :as bean]
             [frontend.state :as state]
             [frontend.util :as util]

src/main/frontend/handler/notification.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.notification
+  "Provides notification related functionality"
   (:require [frontend.state :as state]
             [frontend.util :as util]))
 

src/main/frontend/handler/page.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.page
+  "Provides util handler fns for pages"
   (:require [cljs.reader :as reader]
             [clojure.string :as string]
             [clojure.walk :as walk]

src/main/frontend/handler/paste.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.paste
+(ns ^:no-doc frontend.handler.paste
   (:require [frontend.state :as state]
             [frontend.db :as db]
             [frontend.format.block :as block]

src/main/frontend/handler/plugin.cljs

@@ -1,10 +1,11 @@
 (ns frontend.handler.plugin
+  "System-component-like ns that provides all high level plugin functionality"
   (:require [promesa.core :as p]
             [rum.core :as rum]
             [frontend.util :as util]
             [clojure.walk :as walk]
             [logseq.graph-parser.mldoc :as gp-mldoc]
-            [frontend.handler.notification :as notifications]
+            [frontend.handler.notification :as notification]
             [camel-snake-kebab.core :as csk]
             [frontend.state :as state]
             [medley.core :as medley]
@@ -202,7 +203,7 @@
                                  (.reload pl)
                                  #(do
                                     ;;(if theme (select-a-plugin-theme id))
-                                    (notifications/show!
+                                    (notification/show!
                                       (str (t :plugin/update) (t :plugins) ": " name " - " (.-version (.-options pl))) :success)
                                     (state/consume-updates-coming-plugin payload true))))
 
@@ -210,7 +211,7 @@
                                (p/then
                                  (js/LSPluginCore.register (bean/->js {:key id :url dst}))
                                  (fn [] (when theme (js/setTimeout #(select-a-plugin-theme id) 300))))
-                               (notifications/show!
+                               (notification/show!
                                  (str (t :plugin/installed) (t :plugins) ": " name) :success)))))
 
                        :error
@@ -232,7 +233,7 @@
                                (state/consume-updates-coming-plugin payload true))
 
                              ;; notify human tips
-                             (notifications/show!
+                             (notification/show!
                                (str
                                  (if (= :error type) "[Error]" "")
                                  (str "<" (:id payload) "> ")
@@ -446,7 +447,7 @@
                  (state/set-state! :plugin/active-readme [content item])
                  (state/set-sub-modal! (fn [_] (display))))
           (p/catch #(do (js/console.warn %)
-                        (notifications/show! "No README content." :warn))))
+                        (notification/show! "No README content." :warn))))
       ;; market
       (state/set-sub-modal! (fn [_] (display repo nil))))))
 

src/main/frontend/handler/query.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.query
+  "Provides util handler fns for query"
   (:require [clojure.walk :as walk]))
 
 (defn normalize-query-function

src/main/frontend/handler/recent.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.recent
+  "Fns related to recent pages feature"
   (:require [frontend.db :as db]))
 
 (defn add-page-to-recent!

src/main/frontend/handler/repeated.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.repeated
+  "Provides fns related to schedule and deadline"
   (:require [cljs-time.core :as t]
             [cljs-time.local :as tl]
             [cljs-time.format :as tf]

src/main/frontend/handler/repo.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.repo
+  "System-component-like ns that manages user's repos/graphs"
   (:refer-clojure :exclude [clone])
   (:require [clojure.string :as string]
             [frontend.config :as config]

src/main/frontend/handler/route.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.route
+(ns ^:no-doc frontend.handler.route
   (:require [clojure.string :as string]
             [frontend.config :as config]
             [frontend.date :as date]

src/main/frontend/handler/search.cljs

@@ -1,8 +1,9 @@
 (ns frontend.handler.search
+  "Provides util handler fns for search"
   (:require [clojure.string :as string]
             [frontend.config :as config]
             [frontend.db :as db]
-            [frontend.handler.notification :as notification-handler]
+            [frontend.handler.notification :as notification]
             [frontend.search :as search]
             [frontend.state :as state]
             [frontend.util :as util]
@@ -118,7 +119,7 @@
    (println "Starting to rebuild search indices!")
    (p/let [_ (search/rebuild-indices!)]
      (when notice?
-       (notification-handler/show!
+       (notification/show!
         "Search indices rebuilt successfully!"
         :success)))))
 
@@ -130,6 +131,6 @@
      (when cache-stale?
        (js/console.log "cache stale: " repo)
        (p/let [_ (search/rebuild-indices! repo)]
-         (notification-handler/show!
+         (notification/show!
           "Stale search cache detected. Search indices rebuilt successfully!"
           :success))))))

src/main/frontend/handler/shell.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.shell
+  "Git related handler fns"
   (:require [electron.ipc :as ipc]
             [clojure.string :as string]
             [logseq.graph-parser.util :as gp-util]

src/main/frontend/handler/ui.cljs

@@ -1,4 +1,4 @@
-(ns frontend.handler.ui
+(ns ^:no-doc frontend.handler.ui
   (:require [cljs-time.core :refer [plus days weeks]]
             [dommy.core :as dom]
             [frontend.util :as util]

src/main/frontend/handler/user.cljs

@@ -1,4 +1,5 @@
 (ns frontend.handler.user
+  "Provides user related handler fns like login and logout"
   (:require [frontend.config :as config]
             [frontend.handler.config :as config-handler]
             [frontend.state :as state]

src/main/frontend/idb.cljs

@@ -1,4 +1,5 @@
 (ns frontend.idb
+  "System-component-like ns that provides indexedDB functionality"
   (:require ["/frontend/idbkv" :as idb-keyval :refer [Store]]
             [clojure.string :as string]
             [frontend.config :as config]

src/main/frontend/image.cljs

@@ -1,4 +1,5 @@
 (ns frontend.image
+  "Image related utility fns"
   (:require ["/frontend/exif" :as exif]
             [clojure.string :as string]
             [frontend.date :as date]

src/main/frontend/loader.cljs

@@ -1,4 +1,5 @@
 (ns frontend.loader
+  "Provides fns related to loading js assets"
   (:require [goog.net.jsloader :as jsloader]
             [goog.html.legacyconversions :as conv]
             [cljs-bean.core :as bean]))

src/main/frontend/log.cljs

@@ -1,8 +1,11 @@
 (ns frontend.log
+  "System-component-like ns that encapsulates logging functionality"
   (:require [lambdaisland.glogi :as log]
             [lambdaisland.glogi.console :as glogi-console]
             [frontend.config :as config]))
 
+;; TODO: Move code below into a fn to behave like a system component
+;; instead of having no control over its behavior at require time
 (glogi-console/install!)
 
 (if config/dev?

src/main/frontend/mixins.cljs

@@ -1,4 +1,5 @@
 (ns frontend.mixins
+  "Rum mixins for use in components"
   (:require [rum.core :as rum]
             [goog.dom :as dom]
             [frontend.util :refer [profile] :as util]

src/main/frontend/mobile/core.cljs

@@ -1,9 +1,10 @@
 (ns frontend.mobile.core
+  "Main ns for handling mobile start"
   (:require ["@capacitor/app" :refer [^js App]]
             ["@capacitor/keyboard" :refer [^js Keyboard]]
             [clojure.string :as string]
             [promesa.core :as p]
-            [frontend.fs.capacitor-fs :as mobile-fs]
+            [frontend.fs.capacitor-fs :as capacitor-fs]
             [frontend.handler.editor :as editor-handler]
             [frontend.mobile.deeplink :as deeplink]
             [frontend.mobile.intent :as intent]
@@ -22,7 +23,7 @@
 (defn- ios-init
   "Initialize iOS-specified event listeners"
   []
-  (p/let [path (mobile-fs/ios-ensure-documents!)]
+  (p/let [path (capacitor-fs/ios-ensure-documents!)]
     (println "iOS container path: " (js->clj path)))
 
   (state/pub-event! [:validate-appId])

src/main/frontend/namespaces.cljc

@@ -1,4 +1,4 @@
-(ns frontend.namespaces
+(ns ^:no-doc frontend.namespaces
   #?(:cljs (:require-macros [frontend.namespaces])))
 
 ;; copy from https://github.com/clj-commons/potemkin/issues/31#issuecomment-110689951

src/main/frontend/page.cljs

@@ -1,4 +1,5 @@
 (ns frontend.page
+  "Provides root component for both Logseq app and publishing build"
   (:require [rum.core :as rum]
             [frontend.state :as state]
             [frontend.ui :as ui]

src/main/frontend/publishing.cljs

@@ -1,4 +1,5 @@
 (ns frontend.publishing
+  "Entry ns for publishing build. Handles primary publishing app behaviors"
   (:require [frontend.state :as state]
             [datascript.core :as d]
             [frontend.db :as db]

src/main/frontend/publishing/html.cljs

@@ -1,4 +1,4 @@
-(ns frontend.publishing.html
+(ns ^:no-doc frontend.publishing.html
   (:require-macros [hiccups.core])
   (:require [frontend.state :as state]
             [frontend.util :as util]

src/main/frontend/regex.cljc

@@ -1,4 +1,4 @@
-(ns frontend.regex
+(ns ^:no-doc frontend.regex
   (:require [clojure.string :as string]))
 
 (def re-specials #"([\-\/\\\^\$\*\+\?\.\(\)\|\[\]\{\}])")

src/main/frontend/routes.cljs

@@ -1,4 +1,5 @@
 (ns frontend.routes
+  "Defines routes for use with reitit router"
   (:require [frontend.components.home :as home]
             [frontend.components.repo :as repo]
             [frontend.components.file :as file]

src/main/frontend/rum.cljs

@@ -1,4 +1,5 @@
 (ns frontend.rum
+  "Utility fns for rum"
   (:require [clojure.string :as s]
             [clojure.set :as set]
             [clojure.walk :as w]
@@ -33,6 +34,7 @@
                     x))
                 data)))
 
+;; TODO: Replace this with rum's built in rum.core/adapt-class
 ;; adapted from https://github.com/tonsky/rum/issues/20
 (defn adapt-class
   ([react-class]

src/main/frontend/search.cljs

@@ -1,4 +1,6 @@
 (ns frontend.search
+  "Provides search functionality for a number of features including Cmd-K
+  search. Most of these fns depend on the search protocol"
   (:require [cljs-bean.core :as bean]
             [clojure.string :as string]
             [logseq.graph-parser.config :as gp-config]

src/main/frontend/search/browser.cljs

@@ -1,4 +1,5 @@
 (ns frontend.search.browser
+  "Browser implementation of search protocol"
   (:require [cljs-bean.core :as bean]
             [frontend.search.db :as search-db :refer [indices]]
             [frontend.search.protocol :as protocol]

src/main/frontend/search/db.cljs

@@ -1,4 +1,4 @@
-(ns frontend.search.db
+(ns ^:no-doc frontend.search.db
   (:require [cljs-bean.core :as bean]
             [clojure.string :as string]
             [frontend.db :as db]

src/main/frontend/search/node.cljs

@@ -1,4 +1,5 @@
 (ns frontend.search.node
+  "NodeJS implementation of search protocol"
   (:require [cljs-bean.core :as bean]
             [electron.ipc :as ipc]
             [frontend.search.db :as search-db]

src/main/frontend/search/protocol.cljs

@@ -1,4 +1,4 @@
-(ns frontend.search.protocol)
+(ns ^:no-doc frontend.search.protocol)
 
 (defprotocol Engine
   (query [this q option])

src/main/frontend/security.cljs

@@ -1,4 +1,5 @@
 (ns frontend.security
+  "Provide security focused fns like preventing XSS attacks"
   (:require [clojure.walk :as walk]
             [frontend.util :as util]))
 

src/main/frontend/spec.cljs

@@ -1,4 +1,5 @@
 (ns frontend.spec
+  "Clojure spec related setup and helpers"
   (:require [cljs.spec.alpha :as s]
             [frontend.config :as config]
             [lambdaisland.glogi :as log]

src/main/frontend/state.cljs

@@ -1,4 +1,6 @@
 (ns frontend.state
+  "Provides main application state, fns associated to set and state based rum
+  cursors"
   (:require [cljs-bean.core :as bean]
             [cljs.core.async :as async]
             [clojure.string :as string]

src/main/frontend/storage.cljs

@@ -1,4 +1,6 @@
 (ns frontend.storage
+  "Provides fns for most common operations with localStorage. Assumes
+  localStorage values are edn"
   (:refer-clojure :exclude [get set remove])
   (:require [cljs.reader :as reader]
             [datascript.transit :as dt]

src/main/frontend/template.cljs

@@ -1,4 +1,5 @@
 (ns frontend.template
+  "Provides template related functionality"
   (:require [clojure.string :as string]
             [frontend.date :as date]
             [frontend.state :as state]

src/main/frontend/ui.cljs

@@ -1,8 +1,9 @@
 (ns frontend.ui
+  "Main ns for reusable components"
   (:require [clojure.string :as string]
             [frontend.components.svg :as svg]
             [frontend.context.i18n :refer [t]]
-            [frontend.handler.notification :as notification-handler]
+            [frontend.handler.notification :as notification]
             [frontend.mixins :as mixins]
             [frontend.modules.shortcut.core :as shortcut]
             [frontend.rum :as r]
@@ -275,7 +276,7 @@
            [:div.ml-4.flex-shrink-0.flex
             [:button.inline-flex.text-gray-400.focus:outline-none.focus:text-gray-500.transition.ease-in-out.duration-150.notification-close-button
              {:on-click (fn []
-                          (notification-handler/clear! uid))}
+                          (notification/clear! uid))}
              [:svg.h-5.w-5
               {:fill "currentColor", :view-Box "0 0 20 20"}
               [:path
@@ -781,7 +782,7 @@
   < {:did-catch
      (fn [state error _info]
        (log/error :exception error)
-       (notification-handler/show!
+       (notification/show!
         (str "Error caught by UI!\n " error)
         :error)
        (assoc state ::error error))}

src/main/frontend/ui/date_picker.cljs

@@ -1,4 +1,4 @@
-(ns frontend.ui.date-picker
+(ns ^:no-doc frontend.ui.date-picker
   (:require [cljs-time.core       :refer [after? before? day day-of-week days first-day-of-the-month minus month months plus year]]
             [cljs-time.format     :refer [formatter unparse]]
             [frontend.modules.shortcut.core :as shortcut]

src/main/frontend/util.cljc

@@ -1,4 +1,5 @@
 (ns frontend.util
+  "Main ns for utility fns. This ns should be split up into more focused namespaces"
   #?(:clj (:refer-clojure :exclude [format]))
   #?(:cljs (:require-macros [frontend.util]))
   #?(:cljs (:require