Extended some of the documentation files

 - documentation/chapters/ad-hoc-find.md
 - documentation/chapters/annotation-action.md
 - documentation/chapters/annotation-attribute.md
 - documentation/chapters/annotation-cached.md
 - documentation/chapters/annotation-identify-using.md
 - documentation/chapters/annotation-mark.md
 - documentation/chapters/annotation-must.md
 - documentation/chapters/annotation-named.md
 - documentation/chapters/annotation-post-construct.md
 - documentation/chapters/annotation-wait.md
 - documentation/chapters/browser.md
 - documentation/chapters/by-producers.md
 - documentation/chapters/page-fragment.md
 - documentation/chapters/page.md

Author: slu-it

documentation/chapters/ad-hoc-find.md

@@ -1,38 +1,45 @@
 [Home](../README.md)
 
-# Ad-Hoc finding of Page Objects
-The `Browser`, `Page` and `PageFragment` classes provide entry points to the "ad-hoc finding" API.
-This allows you to apply a more script style approach to your tests.
+# Ad-Hoc Finding API
 
-**Doing so might be useful in the following circumstances:**
+It is not always the best solution to declare page fragments via public `@IdentifyUsing` method.
+Sometimes it is necessary to find a certain fragment programmatically:
 
-- You don't have an unique identification property for initializing a `PageFragment` field and need to take a programmatic 
-approach 
-- You want to rapidly prototype your tests scenarios
-- You want to execute some border cases upon elements and don't like to declare those as fields in your pages
-- Getting to a specific page fragment is not possible using `@IdentifyUsing`
+- Maybe the fragment is only used in very special cases and should therefore not be public...
+- Maybe you need a list of fragments fitting certain parameters which can not be expressed with CSS or XPath..
+- Or maybe are just prototyping your approach and don't want to implement page objects, yet...
+
+For these cases the Ad-Hoc finding API was developed.
+This API can be accessed through a `Browser`, `Page` or a `PageFragment`.
+Depending on where the API is accessed the search context for fragments might differ:
+
+- `Browser`: The whole HTML page is searched for the fragment.
+- `Page`: The whole HTML page is searched for the fragment.
+- `PageFragment`: The area between the page fragment's open and close tags is searched for the fragment. 
+
+There are several ways to start finding fragments, here are a few examples:
 
-## Examples
 ```java
-// find an element by its ID 'fooId' as a GenericElement 
+// find an element by it's ID 'fooId' as a generic element 
 GenericElement element = getBrowser()
     .find("#fooId");
 
-// find many elements by their shared CSS class 'foo' as a stream of GenericElement
+// find many elements by their shared CSS class 'foo' as a stream of generic elements
 Stream<GenericElement> elements = getBrowser()
     .findMany(".foo");
 
-// find a TextField by it's ID - Identification first
+// find an element by it's ID 'textField' as a text field (identifier first)
 TextField textField = getBrowser()
     .findBy(id("textField"))
     .as(TextField.class);
 
-// find a TextField by it's ID - class first
+// find an element by it's ID 'textField' as a text field (class first)
 TextField textField = getBrowser()
     .find(TextField.class)
     .by(id("textField"));
 
-// find all all elements with the CSS class 'foo' within an element with ID 'group' as TextFields
+// find all all elements with the CSS class 'foo'
+// within an element with ID 'group' as a stream of text fields
 Stream<TextField> textFields = getBrowser()
     .find("#group")
     .findBy(css(".foo"))
@@ -41,6 +48,7 @@ Stream<TextField> textFields = getBrowser()
 
 # Linked Documentation
 
-- [Conditions](conditions.md)
-- [ByProducers](by-producers.md)
+- [Page Fragments](page-fragment.md)
 - [Generic Elements](generic-element.md)
+- [ByProducers](by-producers.md)
+- [Conditions](conditions.md)

documentation/chapters/annotation-action.md

@@ -2,12 +2,12 @@
 
 # @Action
 This annotation can be added to methods of `Page` or `PageFragment` subclasses in order to mark these methods as actions.
-Actions can be configured to behave in certain ways:
+Currently the only effect of this annotation the option to delay the execution of annotated methods by setting the 
+property `actions.deceleration` to a certain amount of milliseconds.
 
-- The execution of actions can be delayed by setting the property `actions.deceleration` to a certain amount of milliseconds.
-
-## Example
+> The effects of this annotation will grow in future versions of WebTester
 
+**Example of action method in page:**
 ```java
 public interface FooPage extends Page {
 
@@ -18,3 +18,20 @@ public interface FooPage extends Page {
 
 }
 ```
+
+**Example of action method in page fragment:**
+```java
+public interface BarFragment extends PageFragment {
+ 
+    @Action
+    default void doSomething() {
+        ...
+    }
+ 
+}
+```
+
+# Linked Documentation
+
+- [Pages](page.md)
+- [Page Fragments](page-fragment.md)

documentation/chapters/annotation-attribute.md

@@ -4,26 +4,61 @@
 This annotation can be used within a `PageFragment` subclass in order to retrieve attributes of the underlying element.
 Attribute values (which are returned as Strings from the `WebElement`) will be parsed to the method's return type.
 
+**Supported Types:**
+
+- String
+- Boolean
+- Long
+- Integer
+- Float
+- Double
+- Optional<String>
+- Optional<Boolean>
+- Optional<Long>
+- Optional<Integer>
+- Optional<Float>
+- Optional<Double>
+
 **Constraints:**
 
-- Annotated method must return String, Boolean, Long, Integer, Float, Double or any of those as an Optional<>.
-- Annotated method must not have arguments.
+- Annotated method must not have arguments!
+- Annotated methods have to be part of a page fragment!
 
-## Example
+> It is possible to declare annotated methods in any interface, as long as they are used from a page fragment.
 
+**Example of different attribute methods:**
 ```java
 public interface FooFragment extends PageFragment {
 
+    // returns the string value of the 'value' attribute
     @Attribute("value")
     String value();
 
+    // returns the long value of the 'number' attribute
     @Attribute("number")
     Long number();
 
+    // returns the optional string value of the 'optional' attribute
     @Attribute("optional")
     Optional<String> optional();
 
-    ...
+}
+```
+
+**Example of trait interface with attribute method:**
+```java
+public interface HasValue {
 
+    @Attribute("value")
+    String value();
+ 
+}
+
+public interface BarFragment extends PageFragment, HasValue {
+    // will have access to working 'value()' method
 }
 ```
+
+# Linked Documentation
+
+- [Page Fragments](page-fragment.md)

documentation/chapters/annotation-cached.md

@@ -1,18 +1,20 @@
 [Home](../README.md)
 
 # @Cached
-This annotation can be added to `PageFragment` returning methods of `Page` or `PageFragment` subclasses.
-It will override the configured default caching behavior of the returned page fragment.
+This annotation can be added to `@IdentifyUsing` annotated methods of `Page` or `PageFragment` subclasses.
+It will *override* the configured default caching behavior (property: `caches.enabled`) of the returned page fragment.
 
-> Caching will remember resolved `WebElement` instances for up to 5 seconds.
+> If caching is enabled, resolved `WebElement` instances will be remembered for up to `5` seconds.
+This mechanism is intended to reduce lookup time when executing multiple operations on the same web element in a short 
+period of time where it is unlikely for the element to change. Please note, that enabling caching in AJAX heavy 
+applications might make your tests unstable and increase the occurrence of `StaleElementReferenceException`.
 
-**Constraints:**
+**Cacheable Return Types:**
 
-- Annotated methods must be identification methods (@IdentifyUsing).
-- Annotated methods must not return collection of page fragments.
-
-## Example for Page
+- Single `PageFragment` instances
+- Lists, Sets and Streams of `PageFragment` instances
 
+**Example for page:**
 ```java
 public interface FooPage extends Page {
 
@@ -29,8 +31,7 @@ public interface FooPage extends Page {
 }
 ```
 
-## Example for Page Fragment
-
+**Example for page fragment:**
 ```java
 public interface FooWidget extends PageFragment {
 
@@ -46,3 +47,8 @@ public interface FooWidget extends PageFragment {
 
 }
 ```
+
+# Linked Documentation
+
+- [Pages](page.md)
+- [Page Fragments](page-fragment.md)

documentation/chapters/annotation-identify-using.md

@@ -3,22 +3,19 @@
 # @IdentifyUsing
 This annotation is used to tell the framework how the fragment(s) should be resolved when a page fragment returning method
 is invoked.
-The annotation provides all necessary information to identify the corresponding element(s) in the DOM of the displayed page.
+The annotation provides all necessary information to identify the corresponding element(s) in the DOM of the displayed page:
 
-**Properties:**
+- `how`: Which `ByProducer` to use. I.e. `CssSelector`, `Id`, `XPath` etc. Defaults to `CssSelector`.
+- `value`: The value to be used by the mechanism.
 
-- `value` - A String containing identification data for the method to use the format depends on the used `ByProducer` 
-defined with the `how` property.
-- `how` - The by producer being used to identify the object in the DOM. This is a class reference to any `ByProducer` 
-implementing class.
+Methods annotated with `@IdentifyUsing` must not have arguments and can only return:
 
-**Constraints:**
-
-- Annotated method must return either `PageFragment`, `List<PageFragment>`, `Set<PageFragment>` or `Stream<PageFragment>` 
-(subclasses of `PageFragment` are possible).
-
-## Example on Page
+- Subclass of `PageFragment`
+- `List` of subclass of `PageFragment`
+- `Set` of subclass of `PageFragment`
+- `Stream` of subclass of `PageFragment`
 
+**Example for page:**
 ```java
 public interface FooPage extends Page {
 
@@ -37,8 +34,7 @@ public interface FooPage extends Page {
 }
 ```
 
-## Example as Part of Page Fragment
-
+**Example for page fragment:**
 ```java
 public interface SearchWidget extends PageFragment {
 
@@ -50,3 +46,8 @@ public interface SearchWidget extends PageFragment {
 
 }
 ```
+
+# Linked Documentation
+
+- [Pages](page.md)
+- [Page Fragments](page-fragment.md)

documentation/chapters/annotation-mark.md

@@ -1,34 +1,37 @@
 [Home](../README.md)
 
 # @Mark
-This annotation can be added to methods of `PageFragment` subclasses in order to mark the page fragment in case the method
-is invoked.
-
-The marking feature can be activated / deactivated by setting the `markings.enabled` property.
+This annotation can be added to methods of `PageFragment` subclasses in order to mark the fragment in case the method
+is invoked. The 'marking' is done by setting different style attributes for the underlying element.
 
 The following marking types are available:
 
 - USED - the state of the fragment was changed
 - READ - the state of the fragment was read
 
+The marking feature can be activated / deactivated by setting the `markings.enabled` property.
 The color of each of these types can be configured by changing any of the following properties:
 
 - `markings.used.background`
 - `markings.used.outline`
 - `markings.read.background`
 - `markings.read.outline`
 
-Colors are specified as HEX RGB color codes, i.e. `#ffaa99`.
-
-## Example
+> Colors are specified as HEX RGB color codes, i.e. `#ffaa99`.
 
+**Example:**
 ```java
 public interface FooFragment extends PageFragment {
 
+    // calling this method will mark the FooFragment as used
     @Mark(As.USED)
     default void doSomething() {
         ...
     }
 
 }
 ```
+
+# Linked Documentation
+
+- [Page Fragments](page-fragment.md)