Touch up the documentation (#4245)

* docs: fix broken xrefs in quicktour and kotlin pages

* docs: fix xref target from indexing to references in quicktour

* docs: fix incorrect API usage in quicktour and updates examples

* docs: fix textSearches examples - stale path, malformed save, removed execute()

* docs: fix invalid AsciiDoc syntax - [WARN] admonition and Markdown fences

* docs: fix typos and self-contradiction in configuration page

* docs: complete references page - add MorphiaReference section and fix spacing

* docs: add deprecation notice to updating-old and link from nav

* docs: normalize all page titles to level-1 headings

* docs: rename camelCase page files to kebab-case

* docs: replace MapperOptions with MorphiaConfig and fix prose in mapping page

* docs: update stale 2.x test file paths to 3.0 core/ layout

* docs: use {srcRef} for test link in life-cycle-methods

* docs: fix typos across sharding, schema-validation, life-cycle-methods, migrating, indexing, quicktour

* docs: mark included files as page-partial, fix Update Operators caption

* touch up the docs

Author: evanchooly

docs/modules/ROOT/nav.adoc

@@ -1,6 +1,7 @@
 * xref:index.adoc[Getting Started]
-** xref:migrating.adoc[Migrating]
 ** xref:quicktour.adoc[Quick Tour]
+** xref:migrating.adoc[Migrating]
+*** xref:updating-old.adoc[Legacy Update API (pre-3.0)]
 
 * Features
 ** xref:configuration.adoc[Configuration]
@@ -13,11 +14,11 @@
 ** xref:updates.adoc[Updating]
 ** xref:deletes.adoc[Deleting]
 ** xref:aggregations.adoc[Aggregation]
-** xref:textSearches.adoc[Text Search]
+** xref:text-searches.adoc[Text Search]
 ** xref:references.adoc[References]
 ** xref:transactions.adoc[Transactions]
-** xref:lifeCycleMethods.adoc[Life Cycle Methods]
-** xref:schemaValidation.adoc[Schema Validation]
+** xref:life-cycle-methods.adoc[Life Cycle Methods]
+** xref:schema-validation.adoc[Schema Validation]
 
 * _Support_
 ** xref:issues-help.adoc[Issues & Support]

docs/modules/ROOT/pages/aggregation-expressions.adoc

@@ -1,3 +1,5 @@
+:page-partial:
+
 [%header,cols="1,2,3"]
 |===
 |Operator|Docs|Test Examples

docs/modules/ROOT/pages/aggregation-stages.adoc

@@ -1,3 +1,5 @@
+:page-partial:
+
 [%header,cols="1,2,3"]
 |===
 |Operator|Docs|Test Examples

docs/modules/ROOT/pages/aggregations.adoc

@@ -1,11 +1,11 @@
-== Aggregations
+= Aggregations
 
 The {docsRef}/aggregation[aggregation framework] in MongoDB allows you to define a series (called a pipeline) of operations (called stages) against the data in a collection.
 These pipelines can be used for analytics or they can be used to convert your data from one form to another.
 This guide will not go in to the details of how aggregation works, however.
 The official MongoDB {docsRef}/aggregation[documentation] has extensive tutorials on such details.
 Rather, this guide will focus on the Morphia API. The examples shown here are taken from the
-{srcRef}/morphia/src/test/java/dev/morphia/aggregation/AggregationTest.java[tests] in Morphia itself. You can find the full list in the <<Supported Operators>> section.
+{srcRef}/core/src/test/java/dev/morphia/aggregation/AggregationTest.java[tests] in Morphia itself. You can find the full list in the <<Supported Operators>> section.
 
 Writing an aggregation pipeline starts just like writing a standard query.
 As with querying, we start with the `Datastore`:
@@ -17,7 +17,7 @@ include::example$TestDocsExamples.java[tag=basic]
 
 `aggregate()` takes a `Class` literal. This lets Morphia know which collection to perform this aggregation against. Because of the transformational operations available in the aggregation {docsRef}/core/aggregation-pipeline[pipeline], Morphia can not validate as much as it can with querying so care will need to be taken to ensure document fields actually exist when referencing them in your pipeline.
 
-=== The Pipeline
+== The Pipeline
 
 Aggregation pipelines are comprised of a series stages.
 Our example here with the `group()` stage. This method is the Morphia equivalent of the
@@ -34,7 +34,7 @@ the Morphia equivalent of an {docsRef}/reference/operator/aggregation/group/#gro
 { "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }
 ----
 
-=== Executing the Pipeline
+== Executing the Pipeline
 
 Once your pipeline is complete, you can execute it via the `execute()` method.
 This method optionally takes a `Class` reference for the target type of your aggregation.
@@ -43,7 +43,7 @@ Additionally, you can also include some options to `execute()`.
 We can use the various options on the
 link:javadoc/dev/morphia/aggregation/AggregationOptions.html[AggregationOptions] class to configure how we want the pipeline to execute.
 
-==== $out
+== $out
 
 Depending your use case, you might not want to return the results of your aggregation but simply output them to another collection.
 That's where `$out` comes in.  {docsRef}/reference/operator/aggregation/out/[$out] is an operator that allows the results of a pipeline to be stored in to a named collection.
@@ -66,7 +66,7 @@ that reflects the collection we want to write our output to.  Morphia will use t
 your entities to determine that collection name.  You may also pass a String with the collection name as well if the target collection
 does not correspond to a mapped entity.
 
-==== $merge
+== $merge
 
 {docsRef}/reference/operator/aggregation/merge/[$merge] is a very similar option with a some major differences.
 The biggest difference is that `$merge` can write to existing collections without destroying the existing documents.  `$out` would
@@ -86,7 +86,7 @@ Because there may be existing data in the collection, we need to instruct the op
 In this example, when documents matching we're choosing to replace them and when they don't we're instructing the operation to insert the
 new documents in to the collection.  Other options are defined on `com.mongodb.client.model.MergeOptions` type defined by the Java driver.
 
-=== Supported Operators
+== Supported Operators
 Every effort is made to provide 100% coverage of all the operators offered by MongoDB. A select handful of operators have been excluded
 for reasons of suitability in Morphia.  In short, some operators just don't make sense in Morphia.  Below is listed all the currently
 supported operators.  To see an example of an operator in action, click through to see the test cases for that operator.

docs/modules/ROOT/pages/configuration.adoc

@@ -1,28 +1,28 @@
-== Configuration
+= Configuration
 
-Starting in Morphia 3.0, configuration will be driven via a configuration file.  However programmatic configuration is still supportedfor those who prefer, or need, a more flexible approach. The file should live in your build's resources folder and be named `META-INF/morphia-config.properties`. Reference documentation for the configuration file can be found in the link:++javadoc/dev/morphia/config/MorphiaConfig.html++[javadoc] but
+Starting in Morphia 3.0, configuration will be driven via a configuration file.  However programmatic configuration is still supported for those who prefer, or need, a more flexible approach. The file should live in your build's resources folder and be named `META-INF/morphia-config.properties`. Reference documentation for the configuration file can be found in the link:++javadoc/dev/morphia/config/MorphiaConfig.html++[javadoc] but
 we'll go in depth on a few items here. An example configuration file is included below. All possible configuration elements are listed. However, if the default values are acceptable that element can be safely omitted from your file.
 
 `Morphia.createDatastore()` can be called link:++javadoc/dev/morphia/Morphia.html#createDatastore(com.mongodb.client.MongoClient,dev.morphia.config.MorphiaConfig)++[with]
 and link:++javadoc/dev/morphia/Morphia.html#createDatastore(com.mongodb.client.MongoClient)++[without] an explicit `MorphiaConfig`
-argument.  When not explicitly given a `MorphiaConfig`, Morphia will attempt to load the configuration file at the location show above.
+argument.  When not explicitly given a `MorphiaConfig`, Morphia will attempt to load the configuration file at the location shown above.
 Failing to find a configuration file, it will create a new configuration using the default values which can be found in the javadoc.
 These values are unlikely to be suitable long term but should be sufficient for newcomers looking to test things out a little before
 committing to adopt Morphia.
 
-=== Manually loading configurations
+== Manually loading configurations
 In some cases, you might find the need for multiple configuration files.  Such scenarios include varying test
 environments/configurations, multiple dataset configurations, or externally supplied configurations.  In such cases, you can manually
 load those configurations using link:++javadoc/dev/morphia/config/MorphiaConfig.html#load(java.lang.String)++[MorphiaConfig.load()].  You
 can then pass this instance to `createDatastore()`.
 
-=== Dynamic configuration creation
+== Dynamic configuration creation
 For many, the ability to dynamically create `MorphiaConfig` instances is not just a nicety but a hard requirement.  In this case, there
 are methods on `MorphiaConfig` to return a new version of the configuration with the updated value.  `MorphiaConfig` is immutable,
 however, so be sure to use the returned reference and not the original.  It should also be noted that once a `Datastore` is created using
 a `MorphiaConfig`, that configuration is fixed and can not be changed.  A new `Datastore` would need to be created with the updated version.
 
-=== Collection and property naming
+== Collection and property naming
 
 * `morphia.collection-naming`
 * `morphia.property-naming`
@@ -50,7 +50,7 @@ For the provided strategies, you can simply use the shortened version as shown i
 can enable it by giving the fully qualified classname (fqcn) instead. The same applies everywhere you see `fqcn` in the sample file.
 ====
 
-=== Discriminator keys and values
+== Discriminator keys and values
 
 * `morphia.discriminator`
 * `morphia.discriminator-key`
@@ -66,18 +66,19 @@ The choices here are simpler:
 1. `className()`/`lowerClassName()`
 2. `simpleName()`/`lowerSimpleName()`
 
-Simple name is the fully qualified classname without the package name. These can all be accessed via their named methods on
+Simple name is the class name without the package name. These can all be accessed via their named methods on
 link:++javadoc/dev/morphia/mapping/DiscriminatorFunction.html++[DiscriminatorFunction] and just like the `NamingStrategy` cases, if the
 provided options are not sufficient, you can implement your own by subclassing `DiscriminatorFunction` and implementing your own function.
 
-=== Mapper selection
+== Mapper selection
 
 * `morphia.mapper`
 
 Morphia supports two mapper implementations, selectable via configuration:
 
 1. `reflection` *(default)* — the traditional reflection-based mapper. No additional dependencies required.
-2. `critter` — a bytecode-generation mapper that produces `VarHandle`-based accessors at runtime via Gizmo, with automatic fallback to reflection if generation fails for a given type. Pre-generated models from the `critter-maven` plugin are used when available (AOT path), otherwise models are generated at JVM startup.
+2. `critter` — a bytecode-generation mapper that produces bytecode to handle serialization rather than using reflection.
+This option should give you better performance overall. Pre-generated models from the `critter-maven` plugin are used when available (AOT path), otherwise models are generated at JVM startup.
 
 To enable the critter mapper, add the following to your `META-INF/morphia-config.properties`:
 
@@ -90,7 +91,7 @@ Or pass `-Dmorphia.mapper=critter` on the Maven command line when running tests.
 
 For production deployments, consider using the xref:maven-plugin.adoc[critter-maven plugin] to generate models at build time and eliminate the startup cost entirely.
 
-=== User-defined Codecs
+== User-defined Codecs
 
 * `morphia.codec-provider`
 
@@ -114,13 +115,13 @@ will not only make it consistent with other configurable elements but will make
 the note below about using the ServiceLoader with Java 9 modules.
 ====
 
-==== Property Codecs
+== Property Codecs
 As unusual as is the need for a custom codec to handle types, there are rare cases where how Morphia processes a property on entity needs
 to be customized.  This processing is handled via the
 link:++javadoc/dev/morphia/mapping/codec/MorphiaPropertyCodecProvider.html++[MorphiaPropertyCodecProvider].  Morphia discovers these
 custom implementations via SPI the details of which won't be covered here.
 
-=== Legacy Configuration
+== Legacy Configuration
 
 Morphia can be configured in one of two ways: the legacy mode and the modern mode. The defaults in the configuration code will give you
 the modern configuration and is the recommended way to configure Morphia. However, if you're upgrading an older project, you very likely
@@ -131,16 +132,14 @@ Using the legacy configuration is a matter of defining a few entries in your con
 you already have a `MorphiaConfig` in hand but would like to update it to reflect the legacy style configuration, you can call `.legacy()`
 on that reference and use the resulting `MorphiaConfig` instance.
 
-=== Sample config files
+== Sample config files
 
 .Complete with defaults
 [,txt]
 ----
 include::example$complete-morphia-config.properties[]
 ----
 
----
-
 .Minimal config file
 [,txt]
 ----
@@ -149,32 +148,31 @@ include::example$minimal-morphia-config.properties[]
 
 [NOTE]
 ====
-The minimum config is, indeed, an empty (or even nonexistant) file as there are defaults for each value.  This is intended to "pave the
+The minimum config is, indeed, an empty (or even nonexistent) file as there are defaults for each value.  This is intended to "pave the
 on ramp" for those new to Morphia.  It is expected that some of those values, notably the database and packages fields, will eventually
 be updated with more suitable values.
 ====
----
 
 .Legacy config file
 [,txt]
 ----
 include::example$legacy-morphia-config.properties[]
 ----
 
-[WARN]
+[WARNING]
 ====
-The legacy query factory is deprecated and will be removed in 3.0. It is advisable to switch to the newer query filters based API now to
-avoid breakage.
+The legacy query factory has been removed in 3.0. Switch to the newer query filters based API.
 ====
 
-=== Some notes on ServiceLoader
+== Some notes on ServiceLoader
 
 Morphia provides a number of extensibility points using https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html[the SPI mechanism]
 available in the JVM.  This allows for seamless, config-free inclusion of different functionality.  In general, this works without notice
 because most users will not need to implement such features and so needn't be bothered with such details.  However, if you are one of the
 lucky ones that *does* need to know *and* you use Java modules, please be aware that the usual services file in `META-INF/services` won't
 work.  In order to export your service for Morphia to find you need an entry in your `module-info.java` file as shown below:
 
-```java
+[source,java]
+----
 provides dev.morphia.mapping.codec.MorphiaPropertyCodecProvider with com.foo.MyCodecProvider;
-```
+----

docs/modules/ROOT/pages/deletes.adoc

@@ -1,4 +1,4 @@
-== Deletes
+= Deletes
 
 Queries are used to delete documents from the database as well.
 Using

docs/modules/ROOT/pages/indexing.adoc

@@ -1,4 +1,4 @@
-== Indexing
+= Indexing
 
 Morphia provides annotations that allow developers to define indexes for a collection to be defined alongside the other mapping data on an entity's source.
 In addition to the familiar ascending/descending index types, Morphia and MongoDB support
@@ -10,7 +10,7 @@ setting the `morphia.apply-indexes` to true in the xref:configuration.adoc[confi
 
 There are two ways to define indexes: at the class level and at the field level.
 
-=== Class Level Indexes
+== Class Level Indexes
 
 Class level indexing begins with the link:javadoc/dev/morphia/annotations/Indexes.html[@Indexes] annotation.
 This is a container annotation whose sole purpose is to hold a number of link:javadoc/dev/morphia/annotations/Index.html[@Index] annotations.
@@ -38,7 +38,7 @@ public class IndexExample {
 }
 ----
 
-=== Fields
+== Fields
 
 Which fields to index are defined with the link:javadoc/dev/morphia/annotations/Field.html[@Field] annotation.
 An arbitrary number of link:javadoc/dev/morphia/annotations/Field.html[@Field]s can be given but at least one must be present.
@@ -48,23 +48,23 @@ annotations.
 For most index types, this value is validated by default.
 An exception is made for <<_text_indexing,text indexing>> as discussed below.
 
-=== Index Options
+== Index Options
 
 Options for an index are defined on the link:javadoc/dev/morphia/annotations/IndexOptions.html[@IndexOptions].
-More complete documenation can be found in the {docsRef}/reference/method/db.collection.createIndex/#options[manual].
+More complete documentation can be found in the {docsRef}/reference/method/db.collection.createIndex/#options[manual].
 Using the options allows you to run indexing in the background, e.g. By default, creating an index blocks all other operations on a database.
 When building an index on a collection, the database that holds the collection is unavailable for read or write operations until the index build completes.
 For potentially long running index building operations, consider the **background** operation so that the MongoDB database remains available during the index building operation.
 The MongoDB {docsRef}/core/index-creation/#background-construction[manual] has more detail.
 
-By default Morphia will attempt to validate the fields specified but in some cases that isn't desirable so you can turn it off via the options refernce.  `IndexOptions` lets you define {docsRef}/core/index-ttl/[TTL], {docsRef}/core/index-sparse/[sparse], and {docsRef}/core/index-partial/[partial] indexes as well.  `IndexOptions` can also be used to give an index a more human friendly name.
+By default Morphia will attempt to validate the fields specified but in some cases that isn't desirable so you can turn it off via the options reference.  `IndexOptions` lets you define {docsRef}/core/index-ttl/[TTL], {docsRef}/core/index-sparse/[sparse], and {docsRef}/core/index-partial/[partial] indexes as well.  `IndexOptions` can also be used to give an index a more human friendly name.
 
 [NOTE]
 ====
 Whether user specified or MongoDB generated, index names including their full namespace (i.e. database.collection) cannot be longer than the {docsRef}/reference/limits/#Index-Name-Length[Index Name Limit].
 ====
 
-==== Partial Indexes
+== Partial Indexes
 
 New in MongoDB 3.2, https://docs.mongodb.com/v3.2/core/index-partial/[partial indexes] only index the documents in a collection that meet a specified filter expression thereby reducing storage and maintenance costs.
 A partial filter is defined using a query as shown here:
@@ -122,7 +122,7 @@ A wild card text index declaration would look like this:
 A collection can have at most one text index.
 ====
 
-=== Collation
+== Collation
 
 Collation allows users to specify language-specific rules for string comparison such as rules for lettercase and accent marks.
 A collation can be defined using the `collation()` property on link:javadoc/dev/morphia/annotations/IndexOptions.html[@IndexOptions]

docs/modules/ROOT/pages/kotlin.adoc

@@ -1,4 +1,4 @@
-== Kotlin
+= Kotlin
 
 In general, your Kotlin types should work out of the box with Morphia.
 There are, however, a few interesting cases where they need a little extra help.
@@ -35,4 +35,4 @@ This module should support any
 `ReadWriteProperty` type but is only currently tested against the `notNull()` case.
 
 All that is needed to enable this more targeted support is to simply add the new dependency to your project as shown above and it should magically "Just Work™".
-If you find something that doesn't work in your Kotlin project, please file an xref:/issues-help.adoc[issue].
+If you find something that doesn't work in your Kotlin project, please file an xref:issues-help.adoc[issue].