Declare the etaoin public API

Clearly declaring a public API allows us to freely change what is
internal and invest our effort in being careful to not break what is
public.

We've asked the Etaoin community if we've got this right, but no peep
yet. I'm sure we'll hear plenty of peeps if we've got it wrong when
folks actually start using the next release. If so, we can adjust as
necessary.

Moved what namespaces are deemed internal to impl namespaces and marked
with `:no-doc` metadata.

See clj-commons#430 for details.

Closes clj-commons#430

CHANGELOG.adoc

@@ -9,10 +9,38 @@ A release with an intentional breaking changes is marked with:
 
 Minor Breaking Changes
 
-* https://github.com/clj-commons/etaoin/issues/412[#412]: Rename `etaoin.keys/num-.` to `etaoin.keys/num-dot` +
+* https://github.com/clj-commons/etaoin/issues/412[#412]: Rename `etaoin.keys/num-.` to `etaoin.keys/num-dot`. +
 The symbol `num-.` is technically an invalid Clojure symbol and can confuse tooling. +
 A grep.app for `num-.` found Etaoin itself as the only user of this var.
 If your code uses `etaoin.keys/num-.`, you'll need to rename it to `etaoin.keys/num-dot`.
+* https://github.com/clj-commons/etaoin/issues/430[#430]: Declare the public API.
+We made what we think is a good guess at what the public etaoin API is.
+The following namespaces are now considered internal and subject to change:
++
+[%autowidth]
+|===
+| old namespace | new internal namespace
+
+| `etaoin.client`
+| `etaoin.impl.client`
+
+| `etaoin.driver`
+| `etaoin.impl.driver`
+
+| `etaoin.proc`
+| `etaoin.impl.proc`
+
+| `etaoin.xpath`
+| `etaoin.impl.xpath`
+
+| `etaoin.ide.api`
+| `etaoin.ide.impl.api`
+
+| `etaoin.ide.spec`
+| `etaoin.ide.impl.spec`
+
+|===
+If we got this wrong your code will fail, you will tell us, and we can discuss.
 
 Other Changes
 

src/etaoin/api.clj

@@ -17,13 +17,13 @@
   Phantom.js (Ghostdriver) - obsolete and no longer tested
   https://github.com/detro/ghostdriver/blob/
   "
-  (:require [etaoin.proc   :as proc]
-            [etaoin.client :as client]
+  (:require [etaoin.impl.proc   :as proc]
+            [etaoin.impl.client :as client]
             [etaoin.keys   :as keys]
             [etaoin.query  :as query]
             [etaoin.util   :as util :refer [defmethods]]
-            [etaoin.driver :as drv]
-            [etaoin.xpath  :as xpath]
+            [etaoin.impl.driver :as drv]
+            [etaoin.impl.xpath  :as xpath]
 
             [clojure.tools.logging     :as log]
             [clojure.java.io           :as io]

src/etaoin/ide/flow.clj

@@ -7,8 +7,8 @@
    [clojure.set :as cset]
    [clojure.spec.alpha :as s]
    [etaoin.api :refer :all]
-   [etaoin.ide.api :refer [run-command-with-log str->var]]
-   [etaoin.ide.spec :as spec]))
+   [etaoin.ide.impl.api :refer [run-command-with-log str->var]]
+   [etaoin.ide.impl.spec :as spec]))
 
 
 (declare execute-commands)

src/etaoin/ide/api.clj → src/etaoin/ide/impl/api.clj

@@ -1,4 +1,4 @@
-(ns etaoin.ide.api
+(ns ^:no-doc etaoin.ide.impl.api
   "
   Common Selenium IDE implementation.
   https://www.selenium.dev/selenium-ide/docs/en/api/commands

src/etaoin/ide/spec.clj → src/etaoin/ide/impl/spec.clj

@@ -1,4 +1,4 @@
-(ns etaoin.ide.spec
+(ns ^:no-doc etaoin.ide.impl.spec
   "
   Parsing IDE flow with spec.
   "

src/etaoin/client.cljc → src/etaoin/impl/client.cljc

@@ -1,4 +1,4 @@
-(ns etaoin.client
+(ns ^:no-doc etaoin.impl.client
   (:require [clojure.string :as str]
             [clojure.tools.logging :as log]
             #?(:bb [clj-http.lite.client :as client]

src/etaoin/driver.clj → src/etaoin/impl/driver.clj

@@ -1,4 +1,4 @@
-(ns etaoin.driver
+(ns ^:no-doc etaoin.impl.driver
   "Some utilities to work with driver's data structure.
 
   Links for development:

src/etaoin/proc.clj → src/etaoin/impl/proc.clj

@@ -1,4 +1,4 @@
-(ns etaoin.proc
+(ns ^:no-doc etaoin.impl.proc
   (:require [clojure.java.io :as io]
             [clojure.string :as str]))
 

src/etaoin/xpath.clj → src/etaoin/impl/xpath.clj

@@ -1,4 +1,4 @@
-(ns etaoin.xpath
+(ns ^:no-doc etaoin.impl.xpath
   "A special module to work with XPath language."
   (:require [clojure.string :as string]))
 

src/etaoin/query.clj

@@ -1,7 +1,7 @@
 (ns etaoin.query
   "A module to deal with querying elements."
   (:require [etaoin.util :as util]
-            [etaoin.xpath :as xpath]))
+            [etaoin.impl.xpath :as xpath]))
 
 ;; todo duplicates with api.clj
 (def locator-xpath "xpath")

test/etaoin/unit/proc_test.clj

@@ -2,7 +2,7 @@
   (:require [etaoin.api :refer :all]
             [clojure.java.shell :refer [sh]]
             [clojure.test :refer :all]
-            [etaoin.proc :as proc]
+            [etaoin.impl.proc :as proc]
             [etaoin.test-report]
             [clojure.pprint :as pprint]
             [clojure.string :as str]))

test/etaoin/unit/unit_test.clj

@@ -4,16 +4,16 @@
             [clojure.test :refer :all]
             [etaoin.api :refer :all]
             [etaoin.ide.flow :as ide]
-            [etaoin.ide.spec :as spec]
+            [etaoin.ide.impl.spec :as spec]
             [etaoin.test-report]
-            etaoin.proc))
+            etaoin.impl.proc))
 
 (deftest test-firefox-driver-args
   (with-redefs
-    [etaoin.proc/run  (fn [_ _])
+    [etaoin.impl.proc/run  (fn [_ _])
      wait-running     identity
      create-session   (fn [_ _] "session-key")
-     etaoin.proc/kill identity
+     etaoin.impl.proc/kill identity
      delete-session   identity]
     (testing "Session"
       (with-firefox {} driver

test/etaoin/unit/xpath_test.clj

@@ -1,7 +1,7 @@
 (ns etaoin.unit.xpath-test
   (:require [clojure.test :refer :all]
             [etaoin.test-report]
-            [etaoin.xpath :as xpath]))
+            [etaoin.impl.xpath :as xpath]))
 
 (def xpath-samples
   [[{:tag :a} ".//a"]