From fccb4ade67793c15998107d3b099d8730a00ff06 Mon Sep 17 00:00:00 2001 From: Pascal Seitz Date: Mon, 15 Apr 2024 10:54:53 +0800 Subject: [PATCH] improve document docs --- src/functional_test.rs | 1 + src/schema/document/mod.rs | 26 +++++++++++++++----------- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/src/functional_test.rs b/src/functional_test.rs index f69136b2d8..af2e44ff45 100644 --- a/src/functional_test.rs +++ b/src/functional_test.rs @@ -4,6 +4,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<()> { diff --git a/src/schema/document/mod.rs b/src/schema/document/mod.rs index 941ecbd2ac..16c7eaddfa 100644 --- a/src/schema/document/mod.rs +++ b/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` a mapping of field_ids to their relevant schema value using a +//! - `BTreeMap` a mapping of field_ids to their relevant schema value using a //! BTreeMap. -//! - `HashMap` a mapping of field_ids to their relevant schema value using a HashMap. +//! - `HashMap` 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,10 +97,11 @@ //! 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. //! @@ -105,9 +109,9 @@ //! 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