Add ns linter to deps libs and then add+update ns docstrings

logseq · Sep 21, 2022 · a368cab · a368cab
1 parent 7046054
commit a368cab
Show file tree

Hide file tree

Showing 19 changed files with 47 additions and 15 deletions.
diff --git a/.github/workflows/db.yml b/.github/workflows/db.yml
@@ -91,3 +91,6 @@ jobs:
 
       - name: Lint datalog rules
         run: bb lint:rules
+
+      - name: Lint for namespaces that aren't documented
+        run: bb lint:ns-docstrings
diff --git a/.github/workflows/graph-parser.yml b/.github/workflows/graph-parser.yml
@@ -120,3 +120,6 @@ 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
diff --git a/deps/db/bb.edn b/deps/db/bb.edn
@@ -4,7 +4,7 @@
  {logseq/bb-tasks
   #_{:local/root "../../../bb-tasks"}
   {:git/url "https://github.com/logseq/bb-tasks"
-   :git/sha "abb32ccd26405d56fd28a29d56f3cb902b8c4334"}}
+   :git/sha "1815db538241082a01e95601e23e4290dd64d0c0"}}
 
  :pods
  {clj-kondo/clj-kondo {:version "2022.02.09"}}
@@ -19,6 +19,9 @@
   lint:carve
   logseq.bb-tasks.lint.carve/-main
 
+  lint:ns-docstrings
+  logseq.bb-tasks.lint.ns-docstrings/-main
+
   lint:rules
   {:requires ([logseq.bb-tasks.lint.datalog :as datalog]
               [logseq.db.rules :as rules])

diff --git a/deps/db/src/logseq/db.cljs b/deps/db/src/logseq/db.cljs
@@ -1,4 +1,5 @@
 (ns logseq.db
+  "Main namespace for public db fns"
   (:require [logseq.db.default :as default-db]
             [logseq.db.schema :as db-schema]
             [datascript.core :as d]))

diff --git a/deps/db/src/logseq/db/default.cljs b/deps/db/src/logseq/db/default.cljs
@@ -1,4 +1,5 @@
 (ns logseq.db.default
+  "Provides fns for seeding default data in a logseq db"
   (:require [clojure.string :as string]))
 
 (defonce built-in-pages-names

diff --git a/deps/db/src/logseq/db/schema.cljs b/deps/db/src/logseq/db/schema.cljs
@@ -1,4 +1,5 @@
-(ns logseq.db.schema)
+(ns logseq.db.schema
+  "Main db schema for the Logseq app")
 
 (defonce version 1)
 (defonce ast-version 1)

diff --git a/deps/graph-parser/bb.edn b/deps/graph-parser/bb.edn
@@ -3,8 +3,8 @@
  {logseq/bb-tasks
   #_{:local/root "../../../bb-tasks"}
   {:git/url "https://github.com/logseq/bb-tasks"
-   :git/sha "abb32ccd26405d56fd28a29d56f3cb902b8c4334"}}
-
+   :git/sha "1815db538241082a01e95601e23e4290dd64d0c0"}}
+ 
  :pods
  {clj-kondo/clj-kondo {:version "2022.02.09"}}
 
@@ -16,7 +16,13 @@
   logseq.bb-tasks.lint.large-vars/-main
 
   lint:carve
-  logseq.bb-tasks.lint.carve/-main}
+  logseq.bb-tasks.lint.carve/-main
+
+  lint:ns-docstrings
+  logseq.bb-tasks.lint.ns-docstrings/-main
+
+  lint:minimize-public-vars
+  logseq.bb-tasks.lint.minimize-public-vars/-main}
 
  :tasks/config
  {:large-vars

diff --git a/deps/graph-parser/src/logseq/graph_parser.cljs b/deps/graph-parser/src/logseq/graph_parser.cljs
@@ -1,5 +1,6 @@
 (ns logseq.graph-parser
-  "Main ns used by logseq app to parse graph from source files"
+  "Main ns used by logseq app to parse graph from source files and then save to
+  the given database connection"
   (:require [datascript.core :as d]
             [logseq.graph-parser.extract :as extract]
             [logseq.graph-parser.util :as gp-util]

diff --git a/deps/graph-parser/src/logseq/graph_parser/block.cljs b/deps/graph-parser/src/logseq/graph_parser/block.cljs
@@ -1,5 +1,5 @@
 (ns logseq.graph-parser.block
-  "Block related code needed for graph-parser"
+  "Given mldoc ast, prepares block data in preparation for db transaction"
   (:require [clojure.set :as set]
             [clojure.string :as string]
             [clojure.walk :as walk]

diff --git a/deps/graph-parser/src/logseq/graph_parser/config.cljs b/deps/graph-parser/src/logseq/graph_parser/config.cljs
@@ -1,5 +1,5 @@
 (ns logseq.graph-parser.config
-  "Config that is shared between graph-parser and rest of app"
+  "App config that is shared between graph-parser and rest of app"
   (:require [clojure.set :as set]
             [clojure.string :as string]))
 

diff --git a/deps/graph-parser/src/logseq/graph_parser/extract.cljc b/deps/graph-parser/src/logseq/graph_parser/extract.cljc
@@ -1,4 +1,6 @@
 (ns logseq.graph-parser.extract
+  "Handles extraction of blocks, pages and mldoc ast in preparation for db
+  transaction"
   ;; Disable clj linters since we don't support clj
   #?(:clj {:clj-kondo/config {:linters {:unresolved-namespace {:level :off}
                                         :unresolved-symbol {:level :off}}}})

diff --git a/deps/graph-parser/src/logseq/graph_parser/log.cljs b/deps/graph-parser/src/logseq/graph_parser/log.cljs
@@ -1,6 +1,6 @@
 (ns logseq.graph-parser.log
-  "Minimal logging ns that implements basic lambdaisland.glogi fns. May use
-  glogi later if this ns is used more")
+  "Minimal, logging ns that shims lambdaisland.glogi fns for nbb. Could port
+  glogi to nbb later if this shim gets too big")
 
 (defn error [& msgs]
   (apply js/console.error (map clj->js msgs)))
diff --git a/deps/graph-parser/src/logseq/graph_parser/mldoc.cljc b/deps/graph-parser/src/logseq/graph_parser/mldoc.cljc
@@ -1,4 +1,6 @@
 (ns logseq.graph-parser.mldoc
+  "Wraps https://github.com/logseq/mldoc to parse files into mldoc ast. This ns
+  encapsulates mldoc's json api by only taking and returning edn"
   ;; Disable clj linters since we don't support clj
   #?(:clj {:clj-kondo/config {:linters {:unresolved-namespace {:level :off}
                                         :unresolved-symbol {:level :off}}}})

diff --git a/deps/graph-parser/src/logseq/graph_parser/property.cljs b/deps/graph-parser/src/logseq/graph_parser/property.cljs
@@ -1,5 +1,5 @@
 (ns logseq.graph-parser.property
-  "Property fns needed by graph-parser"
+  "Core vars and util fns for properties"
   (:require [logseq.graph-parser.util :as gp-util]
             [clojure.string :as string]
             [clojure.set :as set]

diff --git a/deps/graph-parser/src/logseq/graph_parser/text.cljs b/deps/graph-parser/src/logseq/graph_parser/text.cljs
@@ -1,4 +1,5 @@
 (ns logseq.graph-parser.text
+  "Miscellaneous text util fns for the parser"
   (:require ["path" :as path]
             [goog.string :as gstring]
             [clojure.string :as string]

diff --git a/deps/graph-parser/src/logseq/graph_parser/utf8.cljs b/deps/graph-parser/src/logseq/graph_parser/utf8.cljs
@@ -1,4 +1,5 @@
-(ns logseq.graph-parser.utf8)
+(ns logseq.graph-parser.utf8
+  "Utf8 utilities used by the parser")
 
 (defonce encoder
   (js/TextEncoder. "utf-8"))

diff --git a/deps/graph-parser/src/logseq/graph_parser/util/block_ref.cljs b/deps/graph-parser/src/logseq/graph_parser/util/block_ref.cljs
@@ -1,5 +1,5 @@
 (ns logseq.graph-parser.util.block-ref
-  "General purpose vars and util fns for block-refs"
+  "Core vars and util fns for block-refs"
   (:require [clojure.string :as string]))
 
 (def left-parens "Opening characters for block-ref" "((")

diff --git a/deps/graph-parser/src/logseq/graph_parser/util/page_ref.cljs b/deps/graph-parser/src/logseq/graph_parser/util/page_ref.cljs
@@ -1,6 +1,6 @@
 (ns logseq.graph-parser.util.page-ref
-  "General purpose vars and util fns for page-ref. Currently this only handles
-a logseq page-ref e.g. [[page name]]"
+  "Core vars and util fns for page-ref. Currently this only handles a logseq
+  page-ref e.g. [[page name]]"
   (:require [clojure.string :as string]))
 
 (def left-brackets "Opening characters for page-ref" "[[")

diff --git a/docs/dev-practices.md b/docs/dev-practices.md
@@ -52,6 +52,13 @@ bb lint:large-vars
 
 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:
+```
+bb lint:ns-docstrings
+```
+
 ### Datalog linting
 
 We use [datascript](https://github.com/tonsky/datascript)'s datalog to power our