docs: Update readme and remove obsolete documents (#1792)

Author: mykola-mokhnach

README.md

@@ -4,31 +4,48 @@
 [![Javadocs](https://www.javadoc.io/badge/io.appium/java-client.svg)](https://www.javadoc.io/doc/io.appium/java-client)
 [![Build Status](https://travis-ci.org/appium/java-client.svg?branch=master)](https://travis-ci.org/appium/java-client)
 
-This is the Java language binding for writing Appium Tests, conforms to [Mobile JSON Wire Protocol](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md)
+This is the Java language bindings for writing Appium Tests that conform to [WebDriver Protocol](https://w3c.github.io/webdriver/)
 
-[API docs](https://www.javadoc.io/doc/io.appium/java-client)
+## v8 Migration
 
-### Features and other interesting information
+Since version 8 Appium Java Client had several major changes, which might require to 
+update your client code. Make sure to follow the [v7 to v8 Migration Guide](https://github.com/appium/java-client/blob/master/docs/v7-to-v8-migration-guide.md)
+in order to streamline the migration process.
 
-[Tech stack](https://github.com/appium/java-client/blob/master/docs/Tech-stack.md)
+## Add Appium java client to your test framework
 
-[How to install the project](https://github.com/appium/java-client/blob/master/docs/Installing-the-project.md)
+### Stable
 
-[WIKI](https://github.com/appium/java-client/wiki)
+#### Maven 
 
-## v8 Migration
+Add the following to pom.xml:
 
-Since version 8 Appium Java Client had several major changes, which might require to 
-update your client code. Make sure to follow the [v7 to v8 Migration Guide](https://github.com/appium/java-client/blob/master/docs/v7-to-v8-migration-guide.md)
-in order to streamline the migration process.
+```xml
+<dependency>
+  <groupId>io.appium</groupId>
+  <artifactId>java-client</artifactId>
+  <version>${version.you.require}</version>
+  <scope>test</scope>
+</dependency>
+```
+
+#### Gradle
+
+Add the following to build.gradle:
+
+```groovy
+dependencies {
+  testImplementation 'io.appium:java-client:${version.you.require}'
+}
+```
 
-## How to install latest java client Beta/Snapshots
+### Beta/Snapshots
 
 Java client project is available to use even before it is officially published to maven central. Refer [jitpack.io](https://jitpack.io/#appium/java-client)
 
-### Maven
+#### Maven
 
- - Add the following to pom.xml:
+Add the following to pom.xml:
 
 ```xml
 <repositories>
@@ -39,7 +56,7 @@ Java client project is available to use even before it is officially published t
 </repositories>
 ```
 
- - Add the dependency:
+Add the dependency:
 
 ```xml
 <dependency>
@@ -49,27 +66,140 @@ Java client project is available to use even before it is officially published t
 </dependency>
 ``` 
 
-### Gradle
+#### Gradle
 
- - Add the JitPack repository to your build file. Add it in your root build.gradle at the end of repositories:
+Add the JitPack repository to your build file. Add it in your root build.gradle at the end of repositories:
 
-```
+```groovy
 allprojects {
     repositories {
-        ...
+        // ...
         maven { url 'https://jitpack.io' }
     }
 }
 ```
 
- - Add the dependency:
+Add the dependency:
 
-```
+```groovy
 dependencies {
     implementation 'com.github.appium:java-client:latest commit id from master branch'
 }
 ```
 
+## Drivers Support
+
+Appium java client has dedicated classes to support the following Appium drivers:
+
+- [UiAutomator2](https://github.com/appium/appium-uiautomator2-driver) and [Espresso](https://github.com/appium/appium-espresso-driver): [AndroidDriver](src/main/java/io/appium/java_client/android/AndroidDriver.java)
+- [XCUITest](https://github.com/appium/appium-xcuitest-driver): [IOSDriver](src/main/java/io/appium/java_client/ios/IOSDriver.java)
+- [Windows](https://github.com/appium/appium-windows-driver): [WindowsDriver](src/main/java/io/appium/java_client/windows/WindowsDriver.java)
+- [Safari](https://github.com/appium/appium-safari-driver): [SafariDriver](src/main/java/io/appium/java_client/safari/SafariDriver.java)
+- [Gecko](https://github.com/appium/appium-geckodriver): [GeckoDriver](src/main/java/io/appium/java_client/gecko/GeckoDriver.java)
+- [Mac2](https://github.com/appium/appium-mac2-driver): [Mac2Driver](src/main/java/io/appium/java_client/mac/Mac2Driver.java)
+
+To automate other platforms that are not listed above you could use 
+[AppiumDriver](src/main/java/io/appium/java_client/AppiumDriver.java) or its custom derivatives.
+
+Appium java client is built on top of Selenium and implements same interfaces that the foundation
+[RemoteWebDriver](https://github.com/SeleniumHQ/selenium/blob/trunk/java/src/org/openqa/selenium/remote/RemoteWebDriver.java)
+does. However, Selenium lib is mostly focused on web browsers automation while
+Appium is universal and covers wide range of possible platforms, e.g. mobile and desktop
+operating systems, IOT devices, etc. Thus, the foundation `AppiumDriver` class in this package
+extends `RemoteWebDriver` with additional features, and makes it more flexible, so it is not so
+strictly focused on web-browser related operations.
+
+## Appium Server Service Wrapper
+
+Appium java client provides a dedicated class to control Appium server execution.
+The class is [AppiumDriverLocalService](src/main/java/io/appium/java_client/service/local/AppiumDriverLocalService.java).
+It allows to run and verify the Appium server **locally** from your test framework code
+and provides several convenient shortcuts. The service could be used as below:
+
+```java
+AppiumDriverLocalService service = AppiumDriverLocalService.buildDefaultService();
+service.start();
+try {
+    // do stuff with drivers
+} finally {
+    service.stop();
+}
+```
+
+You could customize the service behavior, for example, provide custom
+command line arguments or change paths to server executables
+using [AppiumServiceBuilder](src/main/java/io/appium/java_client/service/local/AppiumServiceBuilder.java)
+
+**Note**
+
+> AppiumDriverLocalService does not support the server management on non-local hosts
+
+## Usage Examples
+
+### UiAutomator2
+
+```java
+UiAutomator2Options options = new UiAutomator2Options()
+    .setUdid('123456')
+    .setApp("/home/myapp.apk");
+AndroidDriver driver = new AndroidDriver(
+    // The default URL in Appium 1 is http://127.0.0.1:4723/wd/hub
+    new URL("http://127.0.0.1:4723"), options
+);
+try {
+    WebElement el = driver.findElement(AppiumBy.xpath, "//Button");
+    el.click();
+    driver.getPageSource();
+} finally {
+    driver.quit();
+}
+```
+
+### XCUITest
+
+```java
+XCUITestOptions options = new XCUITestOptions()
+    .setUdid('123456')
+    .setApp("/home/myapp.ipa");
+IOSDriver driver = new IOSDriver(
+    // The default URL in Appium 1 is http://127.0.0.1:4723/wd/hub
+    new URL("http://127.0.0.1:4723"), options
+);
+try {
+    WebElement el = driver.findElement(AppiumBy.accessibilityId, "myId");
+    el.click();
+    driver.getPageSource();
+} finally {
+    driver.quit();
+}
+```
+
+### Any generic driver that does not have a dedicated class
+
+```java
+BaseOptions options = new BaseOptions()
+    .setPlatformName("myplatform")
+    .setAutomationName("mydriver")
+    .amend("mycapability1", "capvalue1")
+    .amend("mycapability2", "capvalue2");
+AppiumDriver driver = new AppiumDriver(
+    // The default URL in Appium 1 is http://127.0.0.1:4723/wd/hub
+    new URL("http://127.0.0.1:4723"), options
+);
+try {
+    WebElement el = driver.findElement(AppiumBy.className, "myClass");
+    el.click();
+    driver.getPageSource();
+} finally {
+    driver.quit();
+}
+```
+
+Check the corresponding driver's READMEs to know the list of capabilities and features it supports.
+
+You could find much more code examples by checking client's 
+[unit and integration tests](src/test/java/io/appium/java_client).
+
 ## Changelog
 *8.2.0*
 - **[ENHANCEMENTS]**

docs/Functions.md

@@ -46,16 +46,15 @@ List<IOSElement> someElements;
 # The example for the crossplatform mobile native testing
 
 ```java
-import io.appium.java_client.MobileElement;
 import io.appium.java_client.pagefactory.*;
 
 @AndroidFindBy(someStrategy) 
 @iOSFindBy(someStrategy) 
-MobileElement someElement;
+WebElement someElement;
 
 @AndroidFindBy(someStrategy) //for the crossplatform mobile native
 @iOSFindBy(someStrategy) //testing
-List<MobileElement> someElements;
+List<WebElement> someElements;
 ```
 
 # The fully cross platform example