API review: docstrings, arglists, publics

Did a sweep through the current Etaoin public API.

Changes to public API can be seen as an addendum to clj-commons#430.

Consistency - exposed as part of public API (were formerly private)
- etaoin.api
  - get-element-value-el
  - get-element-property-el
  - get-element-css-el

Maintainability - deleted
- etaoin.api (used for pointer move action only, moved into fn)
  - default-duration
  - default-origin

Maintainability - no longer exposed (now implementation details)
My default was to make private, but because some are used from macros
this did not always work. For those cases I just marked with :no-doc
metadata:
- etaoin.api
  - default-locator
  - dispatch-driver
  - find-elements*
  - format-date
  - get-pwd
  - join-path
  - locator-css
  - locator-xpath
  - make-screenshot-file-path
  - make-url
  - postmortem-handler
  - process-log
  - proxy-env
  - use-locator
  - with-exception
  - with-locator
- etaoin.dev
  - build-request
  - group-requests
  - log->request
  - parse-json
  - parse-method
  - process-log
  - request?
  - try-parse-int
- etaoin.ide.flow
  - all except for: run-ide-script
- etaoin.ide.main
  - all except for: -main

Updated docstrings focusing on:
- what is returned when return is important
- describing arguments
- adjust/corrected markdown
- linked to other fns via cljdoc wikilinks
- linked to sections in user guide when it seemed helpful
- added toc to etaoin.api ns docstring

Arglists:
- missing arglists explicitly added so that API docs will show proper usage
  (For def and defmulti)
- renamed some arguments where I thought it would make usage clearer

Redundant code:
- there were some instances of defmethod where :safari and :firefox had
identical code. Merged these to use existing internal defmethods macro
to get rid of code duplication.

CHANGELOG.adoc

@@ -14,7 +14,7 @@ The symbol `num-.` is technically an invalid Clojure symbol and can confuse tool
 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.
+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]
@@ -43,6 +43,48 @@ The following namespaces are now considered internal and subject to change:
 | `etaoin.ide.impl.spec`
 
 |===
++
+The following vars are now considered internal and subject to change:
++
+[%autowidth]
+|===
+| namespace | var
+
+.16+|`etaoin.api`
+| `default-locator`
+| `dispatch-driver`
+| `find-elements*`
+| `format-date`
+| `get-pwd`
+| `join-path`
+| `locator-css`
+| `locator-xpath`
+| `make-url`
+| `make-screenshot-file-path`
+| `postmortem-handler`
+| `process-log`
+| `proxy-env`
+| `use-locator`
+| `with-exception`
+| `with-locator`
+
+.8+| `etaoin.dev`
+| `build-request`
+| `group-requests`
+| `log->request`
+| `parse-json`
+| `parse-method`
+| `process-log`
+| `request?`
+| `try-parse-int`
+
+| `etaoin.ide.flow`
+| all except for: `run-ide-script`
+
+| `etaoin.ide.main`
+| all except for: `-main`
+|===
++
 If we got this wrong your code will fail, you will tell us, and we can discuss.
 
 Other Changes
@@ -63,8 +105,10 @@ Fixed.
 * https://github.com/clj-commons/etaoin/issues/444[#444]: Visibility checks fixed for firefox and chrome (thanks https://github.com/daveyarwood[@daveyarwood]!)
 * https://github.com/clj-commons/etaoin/issues/446[#446]: Bump Etaoin dependencies to current releases
 * Docs
+** Reviewed and updated API docstrings
 ** https://github.com/clj-commons/etaoin/issues/393[#393]: Add changelog
 ** https://github.com/clj-commons/etaoin/issues/426[#426]: Reorganize into separate guides
+
 ** https://github.com/clj-commons/etaoin/issues/396[#396]: Move from Markdown to AsciiDoc
 ** User guide
 *** Reviewed, re-organized, hopefully clarified some things

README.adoc

@@ -14,23 +14,23 @@ https://clojars.org/{project-mvn-coords}[image:https://img.shields.io/clojars/v/
 https://babashka.org[image:https://raw.githubusercontent.com/babashka/babashka/master/logo/badge.svg[bb compatible]]
 https://clojurians.slack.com/archives/C7KDM0EKW[image:https://img.shields.io/badge/slack-join_chat-brightgreen.svg[Join chat]]
 
-A pure Clojure implementation of the link:{url-webdriver}[Webdriver] protocol named after link:{url-wiki}[Etaoin Shrdlu] -- a typing machine that came to life after a mysterious note was produced on it.
+A pure Clojure implementation of the link:{url-webdriver}[Webdriver] protocol, named after link:{url-wiki}[Etaoin Shrdlu] -- a typing machine that came to life after a mysterious note was produced on it.
 
 Use the Etaoin library to automate a browser, test your frontend behaviour, simulate human actions or whatever you want.
 
 == Benefits
 
-* Selenium-free: no long dependencies, no tons of downloaded jars, etc.
+* Selenium-free: no big dependencies, no tons of downloaded jars, etc.
 * Lightweight, fast.
 Simple, easy to understand.
-* Compact: just one main module with a couple of helpers.
+* Compact: just one main namespace with a couple of helpers.
 * Declarative: the code is just a list of actions.
 
 == Capabilities
 
 * Currently supports Chrome, Firefox, Safari and Edge.
-* May either connect to a remote driver or run it on your local machine.
-* Run your unit tests directly from Emacs pressing `C-t t` as usual.
+* Can either connect to a remote WebDriver process, or have Etaoin launch one for you.
+* Run your unit tests directly from Emacs by pressing `C-t t` as usual.
 * Can imitate human-like behaviour (delays, typos, etc).
 
 == Documentation
@@ -54,13 +54,12 @@ Ivan's blog-post about pitfalls that can occur when testing UI.
 
 * https://www.exoscale.com/[Exoscale]
 * https://www.flyerbee.com/[Flyerbee]
-* https://www.roomkey.com/[Roomkey]
 * http://www.barrick.com/[Barrick Gold]
 * http://drevidence.com/[Doctor Evidence]
 * https://kevel.com/[Kevel (formerly Adzerk)]
 * https://www.rate.com/[Guaranteed Rate]
 
-You are welcome to submit your company to this list.
+You are most welcome to submit your company or project to this list.
 
 == Versioning
 
@@ -95,8 +94,8 @@ Can be `alpha`, `beta`, `rc1`, etc.
 
 * https://github.com/igrishaev[Ivan Grishaev]
 
-The project is open for your improvements and ideas.
-If any of unit tests fail on your machine please submit an issue giving your OS version, browser and console output.
+Etaoin is open for your improvements and ideas.
+If any of unit tests fail on your machine, please submit an issue giving your OS version, browser and console output.
 
 == License
 

deps.edn

@@ -16,7 +16,7 @@
                       org.slf4j/jcl-over-slf4j {:mvn/version "2.0.0-alpha7"}}
          :main-opts ["-m" "cognitect.test-runner"]}
   :script {:extra-paths ["script"]}
-  ;; for babashka testing, needed for eatoin.ide
+  ;; for babashka testing, needed for etaoin.ide
   :bb-spec {:extra-deps {org.babashka/spec.alpha {:git/url "https://github.com/babashka/spec.alpha"
                                                   :sha "8df0712896f596680da7a32ae44bb000b7e45e68"}}}
   ;; for babashka testing, allows us to use cognitect test-runner

doc/01-user-guide.adoc

@@ -59,7 +59,7 @@ Etaoin's test suite covers the following OSes and browsers for both Clojure and
 
 |===
 
-NOTE: We once did test against PhantomJS, but since work has long ago stopped on this project, we have dropped testing
+NOTE: We did once test against PhantomJS, but since work has long ago stopped on this project, we have dropped testing
 
 == Installation
 
@@ -68,7 +68,7 @@ There are two steps to installation:
 . Add the `etaoin` library as a dependency to your project
 . Install the WebDriver for each web browser that you want to control with Etaoin
 
-=== Installing the Etaoin Library
+=== Add the Etaoin Library Dependency
 
 ==== For Clojure Users
 
@@ -420,7 +420,7 @@ The v2 API has ergonomic `with-<browser>` functions that handle cleanup nicely:
 Replace `chrome` with `firefox`, `edge` or `safari` for other variants.
 See link:{url-doc}[API docs] for details.
 
-See <<parameters>> for all options available when creating a driver.
+See <<driver-options>> for all options available when creating a driver.
 
 == Selecting Elements [[querying]]
 
@@ -747,7 +747,7 @@ Notice:
 * The nth offset of 1 instead of 2. Clojure's nth is 0-based, and our search indexes are 1-based.
 ====
 
-==== Querying a Tree
+==== Querying a Tree [[query-tree]]
 
 `query-tree` pipes selectors.
 Every selector queries elements from the previous one.
@@ -1313,7 +1313,7 @@ Load strategy option of `:none`:
 
 The `:eager` option only works with Firefox at the moment.
 
-=== Actions
+=== Actions [[actions]]
 
 Etaoin supports link:{actions}[Webdriver Actions].
 They are described as "virtual input devices".
@@ -1514,7 +1514,7 @@ The message text and the source type will vary by browser vendor.
 Chrome wipes the logs once they have been read.
 Phantom.js wipes the logs when the page location changes.
 
-=== DevTools: Tracking HTTP Requests, XHR (Ajax)
+=== DevTools: Tracking HTTP Requests, XHR (Ajax) [[devtools]]
 
 You can trace events that come from the DevTools panel.
 This means that everything you see in the developer console now is available through the Etaoin API.
@@ -1899,9 +1899,9 @@ The available `with-postmortem` options are:
  :date-format "yyyy-MM-dd-HH-mm-ss"}
 ----
 
-== Additional Driver Parameters [[parameters]]
+== Driver Options [[driver-options]]
 
-When creating a driver instance, a map of additional parameters can be passed to tweak the WebDriver and web browser behaviour.
+When creating a driver instance, a map of additional parameters can optionally be passed to tweak the WebDriver and web browser behaviour.
 
 Here, for example, we set an explicit path to the chrome WebDriver binary:
 
@@ -2236,7 +2236,7 @@ To connect to an existing WebDriver, specify the `:host` parameter.
 TIP: When the `:host` parameter is not specified Etaoin will create a new WebDriver process.
 
 The `:host` can be a hostname (localhost, some.remote.host.net) or an IP address (127.0.0.1, 183.102.156.31).
-If the port is not specified, the <<parameters,default>> `:port` is assumed.
+If the port is not specified, the <<driver-options,default>> `:port` is assumed.
 
 Example:
 
@@ -2553,8 +2553,7 @@ Example:
   (is found (format "No *.xlsx file found in %s directory." DL-DIR)))
 ----
 
-[[selenium-ide]]
-== Running Selenium IDE files
+== Running Selenium IDE files [[selenium-ide]]
 
 Etaoin can play the files produced by link:{ide}[Selenium IDE].
 Selenium IDE allows you to record web interactions for later playback.
@@ -2605,7 +2604,7 @@ Now that you have a `test.side` file, you could do something like this:
 
 Everything related to the IDE feature can be found under the link:{url-doc}/CURRENT/api/etaoin.ide[etaoin.ide] namespace.
 
-=== CLI Arguments
+=== CLI Arguments [[selenium-ide-cli]]
 
 You may also run a `.side` script from the command line.
 Here is a `clojure` example:
@@ -2668,7 +2667,7 @@ docker run --name geckodriver -p 4444:4444 -d instrumentisto/geckodriver
 To connect to an existing running WebDriver process you need to specify the `:host`.
 In this example `:host` would be `localhost` or `127.0.0.1`.
 The `:port` would be the appropirate port for the running WebDriver process as exposed by docker.
-If the port is not specified, the <<parameters,default>> port is set.
+If the port is not specified, the <<driver-options,default>> port is set.
 
 //:test-doc-blocks/skip
 [source,clojure]

doc/02-developer-guide.adoc

@@ -257,3 +257,9 @@ Etaoin contains a fair number of macros.
 Clj-kondo can need special configuration (including hooks) to understand the effects of these macros.
 So, when adding any new macros, think also about our Etaoin users and our clj-kondo export configuration.
 ====
+
+== Useful References
+
+* https://chromium.googlesource.com/chromium/src/+/master/chrome/test/chromedriver/[chromedriver]
+* https://github.com/mozilla/geckodriver[firefox geckodriver], https://searchfox.org/mozilla-central/source/testing/webdriver[sources]
+* https://github.com/detro/ghostdriver/blob/[Phantom.js (obsolete, no longer tested)]