Touch up the documentation#4245
Merged
Merged
Conversation
…s, migrating, indexing, quicktour
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refreshes the Antora documentation set for Morphia by fixing page titles, links, wording, and some API examples, plus adding clearer guidance around the legacy update API. It mainly improves the docs structure and migration guidance for current 3.x users.
Changes:
- Standardizes many page titles/section headers and fixes assorted spelling, grammar, and xref/path issues.
- Adds a warning banner and nav entry for the legacy pre-3.0 update API page.
- Updates multiple code samples to reflect newer Morphia query/update APIs.
Reviewed changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/modules/ROOT/pages/updating-old.adoc | Adds warning banner clarifying legacy status of old update API docs. |
| docs/modules/ROOT/pages/updates.adoc | Refreshes update API examples and section structure. |
| docs/modules/ROOT/pages/update-operators.adoc | Marks operator table as a partial page. |
| docs/modules/ROOT/pages/transactions.adoc | Normalizes page title level. |
| docs/modules/ROOT/pages/text-searches.adoc | Fixes text search examples and test-source reference. |
| docs/modules/ROOT/pages/sharding.adoc | Updates sharding wording and heading structure. |
| docs/modules/ROOT/pages/schema-validation.adoc | Fixes title and wording around validation config. |
| docs/modules/ROOT/pages/references.adoc | Cleans up title and reference intro wording. |
| docs/modules/ROOT/pages/quicktour.adoc | Fixes typos, links, and query example wording. |
| docs/modules/ROOT/pages/query-filters.adoc | Marks filter table as a partial page. |
| docs/modules/ROOT/pages/queries.adoc | Normalizes headings and updates test-source links. |
| docs/modules/ROOT/pages/migrating.adoc | Fixes grammar and converts fenced blocks to AsciiDoc source blocks. |
| docs/modules/ROOT/pages/maven-plugin.adoc | Normalizes headings in critter Maven plugin docs. |
| docs/modules/ROOT/pages/mapping.adoc | Fixes many wording issues and updates config/xref references. |
| docs/modules/ROOT/pages/life-cycle-methods.adoc | Normalizes headings and adjusts lifecycle docs wording/links. |
| docs/modules/ROOT/pages/kotlin.adoc | Fixes title and issue xref. |
| docs/modules/ROOT/pages/indexing.adoc | Cleans up headings and several spelling/wording issues. |
| docs/modules/ROOT/pages/deletes.adoc | Normalizes page title level. |
| docs/modules/ROOT/pages/configuration.adoc | Updates configuration prose, warnings, and source block formatting. |
| docs/modules/ROOT/pages/aggregations.adoc | Normalizes headings and updates aggregation test reference. |
| docs/modules/ROOT/pages/aggregation-stages.adoc | Marks stages table as a partial page. |
| docs/modules/ROOT/pages/aggregation-expressions.adoc | Marks expressions table as a partial page. |
| docs/modules/ROOT/nav.adoc | Reorders nav entries and adds legacy update API page link. |
Comments suppressed due to low confidence (3)
docs/modules/ROOT/pages/life-cycle-methods.adoc:13
- This link target is still incorrect after the path update. There is no
core/src/test/java/dev/morphia/TestQuery.java; lifecycle examples live under thedev/morphia/test/lifecyclepackage, so the rendered link will be broken.
docs/modules/ROOT/pages/text-searches.adoc:40 Querydoes not expose a publiciterator(FindOptions)overload; the options have to be supplied todatastore.find(..., new FindOptions())instead. This snippet therefore won't compile for readers following the docs.
docs/modules/ROOT/pages/text-searches.adoc:22- This source link still points at a non-existent test path. The actual file lives under
core/src/test/java/dev/morphia/test/query/TestTextSearching.java, so the rendered docs link will 404.
| {docsRef}/reference/glossary/#term-tailable-cursor[tailable cursor]. | ||
| An example of this feature in action can be found in the | ||
| {srcRef}/morphia/src/test/java/dev/morphia/TestQuery.java[unit tests] in the `testTailableCursors()` test: | ||
| {srcRef}/core/src/test/java/dev/morphia/TestQuery.java[unit tests] in the `testTailableCursors()` test: |
| 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. |
Comment on lines
+98
to
+101
| .find(Hotel.class, new UpdateOptions() | ||
| .upsert(true)) | ||
| .filter(gt("stars", 100)) | ||
| .update() | ||
| .execute(new UpdateOptions() | ||
| .upsert(true)); | ||
| .update(); |
Comment on lines
+126
to
+128
| .find(Hotel.class, new ModifyOptions() | ||
| .returnDocument(ReturnDocument.AFTER)) | ||
| .modify(UpdateOperators.set("address.city", "Ottawa")); |
| This is useful when you need to only return a smaller view of a larger object. | ||
| Borrowing from the | ||
| {srcRef}/morphia/src/test/java/dev/morphia/TestQuery.java[unit tests], this is an example of this feature in action: | ||
| {srcRef}/core/src/test/java/dev/morphia/TestQuery.java[unit tests], this is an example of this feature in action: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fix various misspellings, formatting, and content errors