docstring cleanup (#12711)

Adding the missing docstrings to make the linter complain a little less.

src/metabase/api/common/internal.clj

@@ -55,16 +55,16 @@
 (defn- dox-for-schema
   "Look up the docstring for `schema` for use in auto-generated API documentation. In most cases this is defined by
   wrapping the schema with `with-api-error-message`."
-  [schema]
+  [schema route-str]
   (if-not schema
     ""
     (or (su/api-error-message schema)
         ;; Don't try to i18n this stuff! It's developer-facing only.
         (when config/is-dev?
           (log/warn
-           (u/format-color 'red (str "We don't have a nice error message for schema: %s\n"
+           (u/format-color 'red (str "We don't have a nice error message for schema: %s defined at %s\n"
                                      "Consider wrapping it in `su/with-api-error-message`.")
-             (u/pprint-to-str schema)))))))
+             (u/pprint-to-str schema) route-str))))))
 
 (defn- param-name
   "Return the appropriate name for this `param-symb` based on its `schema`. Usually this is just the name of the
@@ -77,11 +77,11 @@
 (defn- format-route-schema-dox
   "Generate the `params` section of the documentation for a `defendpoint`-defined function by using the
   `param-symb->schema` map passed in after the argslist."
-  [param-symb->schema]
+  [param-symb->schema route-str]
   (when (seq param-symb->schema)
     (str "\n\n##### PARAMS:\n\n"
          (str/join "\n\n" (for [[param-symb schema] param-symb->schema]
-                            (format "*  **`%s`** %s" (param-name param-symb schema) (dox-for-schema schema)))))))
+                            (format "*  **`%s`** %s" (param-name param-symb schema) (dox-for-schema schema route-str)))))))
 
 (defn- format-route-dox
   "Return a markdown-formatted string to be used as documentation for a `defendpoint` function."
@@ -89,7 +89,7 @@
   (str (format "## `%s`" route-str)
        (when (seq docstr)
          (str "\n\n" docstr))
-       (format-route-schema-dox param->schema)))
+       (format-route-schema-dox param->schema route-str)))
 
 (defn- contains-superuser-check?
   "Does the BODY of this `defendpoint` form contain a call to `check-superuser`?"

src/metabase/api/database.clj

@@ -173,6 +173,12 @@
       include-tables?             add-tables
       include-saved-questions-db? (add-saved-questions-virtual-database :include-tables? include-saved-questions-tables?))))
 
+(def FetchAllIncludeValues
+  "Schema for matching the include parameter of the GET / endpoint"
+  (su/with-api-error-message
+    (s/maybe (s/eq "tables"))
+    (deferred-tru "include must be either empty or the value 'tables'")))
+
 (api/defendpoint GET "/"
   "Fetch all `Databases`.
 
@@ -189,7 +195,7 @@
   [include_tables include_cards include saved]
   {include_tables (s/maybe su/BooleanString)
    include_cards  (s/maybe su/BooleanString)
-   include        (s/maybe (s/eq "tables"))
+   include        FetchAllIncludeValues
    saved          (s/maybe su/BooleanString)}
   (when (and config/is-dev?
              (or include_tables include_cards))

src/metabase/api/testing.clj

@@ -12,11 +12,13 @@
   (str "frontend/test/snapshots/" (str/replace snapshot-name #"\W" "_") ".sql"))
 
 (api/defendpoint POST "/snapshot/:name"
+  "Snapshot the database for testing purposes."
   [name]
   (jdbc/query (db/connection) ["SCRIPT TO ?" (snapshot-path-for-name name)])
   nil)
 
 (api/defendpoint POST "/restore/:name"
+  "Restore a database snapshot for testing purposes."
   [name]
   (jdbc/execute! (db/connection) ["DROP ALL OBJECTS"])
   (jdbc/execute! (db/connection) ["RUNSCRIPT FROM ?" (snapshot-path-for-name name)])

src/metabase/api/transform.clj

@@ -8,6 +8,7 @@
              [specs :as transform.specs]]))
 
 (api/defendpoint GET "/:db-id/:schema/:transform-name"
+  "Look up a database schema transform"
   [db-id schema transform-name]
   (api/check-403 (perms/set-has-full-permissions? @api/*current-user-permissions-set*
                    (perms/object-path db-id schema)))

src/metabase/api/util.clj

@@ -37,6 +37,7 @@
   {:token (crypto-random/hex 32)})
 
 (api/defendpoint GET "/bug_report_details"
+  "Returns version and system information relevant to filing a bug report against Metabase."
   []
   (api/check-superuser)
   {:system-info   (troubleshooting/system-info)

src/metabase/models/native_query_snippet.clj

@@ -5,7 +5,9 @@
             [metabase.models.native-query-snippet.permissions :as snippet.perms]
             [metabase.plugins.classloader :as classloader]
             [metabase.util :as u]
-            [metabase.util.i18n :refer [tru]]
+            [metabase.util
+             [i18n :refer [deferred-tru tru]]
+             [schema :as su]]
             [schema.core :as s]
             [toucan
              [db :as db]
@@ -55,7 +57,9 @@
 
 (def NativeQuerySnippetName
   "Schema checking that snippet names do not include \"}\" or start with spaces."
-  (s/pred (every-pred
-           string?
-           (complement #(boolean (re-find #"^\s+" %)))
-           (complement #(boolean (re-find #"}" %))))))
+  (su/with-api-error-message
+   (s/pred (every-pred
+            string?
+            (complement #(boolean (re-find #"^\s+" %)))
+            (complement #(boolean (re-find #"}" %)))))
+   (deferred-tru "snippet names cannot include '}' or start with spaces")))

src/metabase/models/user.clj

@@ -15,7 +15,7 @@
              [permissions-group-membership :as perm-membership :refer [PermissionsGroupMembership]]
              [session :refer [Session]]]
             [metabase.util
-             [i18n :as i18n :refer [trs]]
+             [i18n :as i18n :refer [deferred-tru trs]]
              [schema :as su]]
             [schema.core :as s]
             [toucan
@@ -163,7 +163,9 @@
 
 (def LoginAttributes
   "Login attributes, currently not collected for LDAP or Google Auth. Will ultimately be stored as JSON."
-  {su/KeywordOrString s/Any})
+  (su/with-api-error-message
+      {su/KeywordOrString s/Any}
+    (deferred-tru "login attribute keys must be a keyword or string")))
 
 (def NewUser
   "Required/optionals parameters needed to create a new user (for any backend)"

test/metabase/api/native_query_snippet_test.clj

@@ -22,7 +22,7 @@
 (defn- name-schema-error?
   [response]
   (str/starts-with? (or (get-in response [:errors :name]) "")
-                    "Value does not match schema: "))
+                    "snippet names cannot include"))
 
 (deftest list-snippets-api-test
   (testing "GET /api/native-query-snippet"