improve document docs (#2359)

src/functional_test.rs

@@ -6,6 +6,7 @@ use rand::{thread_rng, Rng};
 
 use crate::indexer::index_writer::MEMORY_BUDGET_NUM_BYTES_MIN;
 use crate::schema::*;
+#[allow(deprecated)]
 use crate::{doc, schema, Index, IndexSettings, IndexSortByField, IndexWriter, Order, Searcher};
 
 fn check_index_content(searcher: &Searcher, vals: &[u64]) -> crate::Result<()> {

src/schema/document/mod.rs

@@ -5,22 +5,24 @@
 //! - [Value] which provides tantivy with a way to access the document's values in a common way
 //!   without performing any additional allocations.
 //! - [DocumentDeserialize] which implements the necessary code to deserialize the document from the
-//!   doc store.
+//!   doc store. If you are fine with fetching [TantivyDocument] from the doc store, you can skip
+//!   implementing this trait for your type.
 //!
 //! Tantivy provides a few out-of-box implementations of these core traits to provide
 //! some simple usage if you don't want to implement these traits on a custom type yourself.
 //!
 //! # Out-of-box document implementations
-//! - [Document] the old document type used by Tantivy before the trait based approach was
+//! - [TantivyDocument] the old document type used by Tantivy before the trait based approach was
 //!   implemented. This type is still valid and provides all of the original behaviour you might
 //!   expect.
-//! - `BTreeMap<Field, Value>` a mapping of field_ids to their relevant schema value using a
+//! - `BTreeMap<Field, OwnedValue>` a mapping of field_ids to their relevant schema value using a
 //!   BTreeMap.
-//! - `HashMap<Field, Value>` a mapping of field_ids to their relevant schema value using a HashMap.
+//! - `HashMap<Field, OwnedValue>` a mapping of field_ids to their relevant schema value using a
+//!   HashMap.
 //!
 //! # Implementing your custom documents
 //! Often in larger projects or higher performance applications you want to avoid the extra overhead
-//! of converting your own types to the Tantivy [Document] type, this can often save you a
+//! of converting your own types to the [TantivyDocument] type, this can often save you a
 //! significant amount of time when indexing by avoiding the additional allocations.
 //!
 //! ### Important Note
@@ -46,6 +48,7 @@
 //!
 //! impl Document for MyCustomDocument {
 //!     // The value type produced by the `iter_fields_and_values` iterator.
+//!     // tantivy already implements the Value trait for serde_json::Value.
 //!     type Value<'a> = &'a serde_json::Value;
 //!     // The iterator which is produced by `iter_fields_and_values`.
 //!     // Often this is a simple new-type wrapper unless you like super long generics.
@@ -94,20 +97,21 @@
 //! implementation for.
 //!
 //! ## Implementing custom values
-//! Internally, Tantivy only works with `ReferenceValue` which is an enum that tries to borrow
-//! as much data as it can, in order to allow documents to return custom types, they must implement
-//! the `Value` trait which provides a way for Tantivy to get a `ReferenceValue` that it can then
+//! In order to allow documents to return custom types, they must implement
+//! the [Value] trait which provides a way for Tantivy to get a `ReferenceValue` that it can then
 //! index and store.
+//! Internally, Tantivy only works with `ReferenceValue` which is an enum that tries to borrow
+//! as much data as it can
 //!
 //! Values can just as easily be customised as documents by implementing the `Value` trait.
 //!
 //! The implementor of this type should not own the data it's returning, instead it should just
 //! hold references of the data held by the parent [Document] which can then be passed
 //! on to the [ReferenceValue].
 //!
-//! This is why `Value` is implemented for `&'a serde_json::Value` and `&'a
-//! tantivy::schema::Value` but not for their owned counterparts, as we cannot satisfy the lifetime
-//! bounds necessary when indexing the documents.
+//! This is why [Value] is implemented for `&'a serde_json::Value` and
+//! [&'a tantivy::schema::document::OwnedValue](OwnedValue) but not for their owned counterparts, as
+//! we cannot satisfy the lifetime bounds necessary when indexing the documents.
 //!
 //! ### A note about returning values
 //! The custom value type does not have to be the type stored by the document, instead the