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]