From af6016ae967f9cebcbabaa14b46ab550b4953035 Mon Sep 17 00:00:00 2001
From: Pierre Hubert <pierre.git@communiquons.org>
Date: Mon, 19 Dec 2022 12:30:33 +0100
Subject: [PATCH] Add documentation

---
 src/lib.rs | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 2178450..1f26d4b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,39 @@
+//! # Grammalecte Rust Client
+//!
+//! This crate is a Rust client to the Grammalecte server API.
+//!
+//! Grammalecte is an Open Source software that allows to do
+//! french spell-checking.
+//!
+//! ## Integrated server
+//! The optional feature `embedded-server` allows you to spin up an
+//! temporary web server that will act as Grammalecte backend, instead
+//! of targetting an existing instance:
+//!
+//! ```rust,no_run
+//! use grammalecte_client::GrammalecteClient;
+//!
+//! let msg = "Les ange sont inssuportables!";
+//! let res = GrammalecteClient::start_server()
+//!             .unwrap()
+//!             .spell_check(msg)
+//!             .await
+//!             .unwrap();
+//! println!("RESULT = {:#?}", res);
+//! ```
+//!
+//! ## Suggestion
+//! You can also ask Grammalecte to give you valid alternatives words:
+//! ```rust,no_run
+//! let res = GrammalecteClient::start_server()
+//!             .unwrap()
+//!             .suggest("bonjou")
+//!             .await
+//!             .unwrap();
+//! assert!(res.suggestions.contains(&"bonjour".to_string()));
+//! println!("RESULT = {:#?}", res);
+//! ```
+
 #[cfg(feature = "embedded-server")]
 use crate::server::EmbeddedServer;
 use std::collections::HashMap;
@@ -150,6 +186,7 @@ pub enum GramOpt {
 }
 
 impl GramOpt {
+    /// Get the technical ID of the Grammalecte option
     pub fn id(&self) -> &'static str {
         match self {
             GramOpt::SignesTypographiques => "typo",
@@ -208,6 +245,7 @@ pub struct CheckResult {
     pub paragraphs: Vec<Paragraph>,
 }
 
+/// Check spell result of a given paragraph
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct Paragraph {
     #[serde(rename = "iParagraph")]
@@ -218,6 +256,7 @@ pub struct Paragraph {
     pub spelling: Vec<SpellingError>,
 }
 
+/// Single grammar error
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct GrammarError {
     #[serde(rename = "nStart")]
@@ -240,6 +279,7 @@ pub struct GrammarError {
     pub url: String,
 }
 
+/// Spelling error information
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct SpellingError {
     pub i: usize,
@@ -253,11 +293,13 @@ pub struct SpellingError {
     pub error_type: String,
 }
 
+/// Response to a suggestion request
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct SuggestResult {
     suggestions: Vec<String>,
 }
 
+/// The Grammalecte client itself
 pub struct GrammalecteClient {
     base_url: String,