Merge #1532

1532: Start writing documentation for newcomers r=MarinPostma a=irevoire



Co-authored-by: Tamo <tamo@meilisearch.com>

meilisearch-http/src/index_controller/dump_actor/mod.rs

@@ -37,7 +37,7 @@ pub trait DumpActorHandle {
     async fn create_dump(&self) -> Result<DumpInfo>;
 
     /// Return the status of an already created dump
-    /// Implementation: [handle_impl::DumpActorHandleImpl::dump_status]
+    /// Implementation: [handle_impl::DumpActorHandleImpl::dump_info]
     async fn dump_info(&self, uid: String) -> Result<DumpInfo>;
 }
 

meilisearch-http/src/lib.rs

@@ -1,3 +1,43 @@
+//! # MeiliSearch
+//! Hello there, future contributors. If you are here and see this code, it's probably because you want to add a super new fancy feature in MeiliSearch or fix a bug and first of all, thank you for that!
+//!
+//! To help you in this task, we'll try to do a little overview of the project.
+//! ## Milli
+//! [Milli](https://github.com/meilisearch/milli) is the core library of MeiliSearch. It's where we actually index documents and perform searches. Its purpose is to do these two tasks as fast as possible. You can give an update to milli, and it'll uses as many cores as provided to perform it as fast as possible. Nothing more. You can perform searches at the same time (search only uses one core).
+//! As you can see, we're missing quite a lot of features here; milli does not handle multiples indexes, it can't queue updates, it doesn't provide any web / API frontend, it doesn't implement dumps or snapshots, etc...
+//!
+//! ## `Index` module
+//! The [index] module is what encapsulates one milli index. It abstracts over its transaction and isolates a task that can be run into a thread. This is the unit of interaction with milli.
+//! If you add a feature to milli, you'll probably need to add it in this module too before exposing it to the rest of meilisearch.
+//!
+//! ## `IndexController` module
+//! To handle multiple indexes, we created an [index_controller]. It's in charge of creating new indexes, keeping references to all its indexes, forward asynchronous updates to its indexes, and provide an API to search in its indexes synchronously.
+//! To achieves this goal, we use an [actor model](https://en.wikipedia.org/wiki/Actor_model).
+//!
+//! ### The actor model
+//! Every actor is composed of at least three files:
+//! - `mod.rs` declare and import all the files used by the actor. We also describe the interface (= all the methods) used to interact with the actor. If you are not modifying anything inside of an actor, this is usually all you need to see.
+//! - `handle_impl.rs` implements the interface described in the `mod.rs`; in reality, there is no code logic in this file. Every method is only wrapping its parameters in a structure that is sent to the actor. This is useful for test and futureproofing.
+//! - `message.rs` contains an enum that describes all the interactions you can have with the actor.
+//! - `actor.rs` is used to create and execute the actor. It's where we'll write the loop looking for new messages and actually perform the tasks.
+//!
+//! MeiliSearch currently uses four actors:
+//! - [`uuid_resolver`](index_controller/uuid_resolver/index.html) hold the association between the user-provided indexes name and the internal [`uuid`](https://en.wikipedia.org/wiki/Universally_unique_identifier) representation we use.
+//! - [`index_actor`](index_controller::index_actor) is our representation of multiples indexes. Any request made to MeiliSearch that needs to talk to milli will pass through this actor.
+//! - [`update_actor`](index_controller/update_actor/index.html) is in charge of indexes updates. Since updates can take a long time to receive and  process, we need to:
+//!   1. Store them as fast as possible so we can continue to receive other updates even if nothing has been processed
+//!   2. Feed the `index_actor` with a new update every time it finished its current job.
+//! - [`dump_actor`](index_controller/dump_actor/index.html) this actor handle the  [dumps](https://docs.meilisearch.com/reference/api/dump.html). It needs to contact all the others actors and create a dump of everything that was currently happening.
+//!
+//! ## Data module
+//! The [data] module provide a unified interface to communicate with the index controller and other services (snapshot, dumps, ...), initialize the MeiliSearch instance
+//!
+//! ## HTTP server
+//! To handle the web and API part, we are using [actix-web](https://docs.rs/actix-web/); you can find all routes in the [routes] module.
+//! Currently, the configuration of actix-web is made in the [lib.rs](crate).
+//! Most of the routes use [extractors] to handle the authentication.
+
+#![allow(rustdoc::private_intra_doc_links)]
 pub mod data;
 #[macro_use]
 pub mod error;