Documentation updates for return types (#893)

* docs(axum): add return type docs for ShuttleAxum

* docs(poem): add return type docs for poem

* docs(poise): return type docs for poise based service

* docs(rocket): add return type docs for Rocket

* docs(salvo): add return types for salvo

* style: add closing code fence for docs

* docs(thruster): add return type docs for thruster

* docs(warp): return type docs for the warp service

* docs(tide): update return type for tide

* docs(service-errors): add documentation for service error types

* style: fix format error on services

* style(errors): fix formatting issues

* chore: complete merge of the upstream changes

* docs(poem): add return type docs for poem

* docs(poise): return type docs for poise based service

* docs(rocket): add return type docs for Rocket

* docs(salvo): add return types for salvo

* style: add closing code fence for docs

* docs(thruster): add return type docs for thruster

* docs(warp): return type docs for the warp service

* docs(tide): update return type for tide

* docs(service-errors): add documentation for service error types

* style: fix format error on services

* style(errors): fix formatting issues

* build: update cargo dependencies on cargo.lock

* docs(axum): add type annotation for ShuttleAxum

* docs(poem): complete the type docs for passing tests

* style(poem): reformat code for poem lib

* docs(rocket): update type docs for ShuttleRocket

* docs(salvo): update docs for salvo to pass tests

* docs(thruster): update the docs for test passage

* docs(tide): update type docs for tide

* docs(axum): update docs to align with examples

* docs(poem): update docs to align with official docs

* docs(rocket): update the example to align with official docs

* docs(salvo): update docs to align with official examples

* docs(thruster): update docs to align with official examples

* docs(tide): update docs to align with official example

* docs(warp): update docs to align with the official examples

* docs(poise): update docs with the official examples

* style: refomat doc-tests for compliance

* docs: trim service error comment

Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>

* docs: use root endpoint

* docs: remove more /hello

* nits

* docs: fix poise doc

---------

Co-authored-by: Iulian Barbu <14218860+iulianbarbu@users.noreply.github.com>
Co-authored-by: Oddbjørn Grødem <29732646+oddgrd@users.noreply.github.com>
Co-authored-by: jonaro00 <54029719+jonaro00@users.noreply.github.com>

service/src/error.rs

@@ -2,16 +2,22 @@
 
 use thiserror::Error;
 
+/// An error that can occur in the process of building and deploying a service.
 #[derive(Debug, Error)]
 pub enum Error {
+    /// An Input/Output error.
     #[error("IO error: {0}")]
     Io(#[from] std::io::Error),
+    /// An Error related to the database.
     #[error("Database error: {0}")]
     Database(String),
+    /// An error related to the build process.
     #[error("Panic occurred in shuttle_service::main`: {0}")]
     BuildPanic(String),
+    /// An error related to the bind process.
     #[error("Panic occurred in `Service::bind`: {0}")]
     BindPanic(String),
+    /// An error related to parsing the Secrets.toml file.
     #[error("Failed to interpolate string. Is your Secrets.toml correct?")]
     StringInterpolation(#[from] strfmt::FmtError),
     #[error(transparent)]

services/shuttle-actix-web/src/lib.rs

@@ -6,7 +6,7 @@
 //! use actix_web::{get, web::ServiceConfig};
 //! use shuttle_actix_web::ShuttleActixWeb;
 //!
-//! #[get("/hello")]
+//! #[get("/")]
 //! async fn hello_world() -> &'static str {
 //!     "Hello World!"
 //! }

services/shuttle-axum/src/lib.rs

@@ -1,5 +1,7 @@
 //! Shuttle service integration for the Axum web framework.
+//!
 //! ## Example
+//!
 //! ```rust,no_run
 //! use axum::{routing::get, Router};
 //!
@@ -9,7 +11,7 @@
 //!
 //! #[shuttle_runtime::main]
 //! async fn axum() -> shuttle_axum::ShuttleAxum {
-//!     let router = Router::new().route("/hello", get(hello_world));
+//!     let router = Router::new().route("/", get(hello_world));
 //!
 //!     Ok(router.into())
 //! }
@@ -39,5 +41,23 @@ impl From<axum::Router> for AxumService {
         Self(router)
     }
 }
-/// The return type that should be returned from the [shuttle_runtime::main] function.
+
+/// Return type from the `[shuttle_runtime::main]` macro for a Axum-based service.
+///
+/// ## Example
+///
+/// ```rust,no_run
+/// use axum::{routing::get, Router};
+///
+/// async fn hello_world() -> &'static str {
+///     "Hello, world!"
+/// }
+///
+/// #[shuttle_runtime::main]
+/// async fn axum() -> shuttle_axum::ShuttleAxum {
+///     let router = Router::new().route("/", get(hello_world));
+///
+///     Ok(router.into())
+/// }
+/// ```
 pub type ShuttleAxum = Result<AxumService, Error>;

services/shuttle-poem/src/lib.rs

@@ -11,7 +11,7 @@
 //!
 //! #[shuttle_runtime::main]
 //! async fn poem() -> ShuttlePoem<impl poem::Endpoint> {
-//!     let app = Route::new().at("/hello", get(hello_world));
+//!     let app = Route::new().at("/", get(hello_world));
 //!
 //!     Ok(app.into())
 //! }
@@ -45,5 +45,23 @@ where
     }
 }
 
-/// The return type that should be returned from the [shuttle_runtime::main] function.
+/// Return type from the `[shuttle_runtime::main]` macro for a Poem-based service.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// use poem::{get, handler, Route};
+/// use shuttle_poem::ShuttlePoem;
+/// #[handler]
+/// fn hello_world() -> &'static str {
+///     "Hello, world!"
+/// }
+///
+/// #[shuttle_runtime::main]
+/// async fn poem() -> ShuttlePoem<impl poem::Endpoint> {
+///     let app = Route::new().at("/", get(hello_world));
+///
+///     Ok(app.into())
+/// }
+/// ```
 pub type ShuttlePoem<T> = Result<PoemService<T>, shuttle_runtime::Error>;

services/shuttle-poise/src/lib.rs

@@ -1,5 +1,7 @@
 //! Shuttle service integration for the Poise discord bot framework.
+//!
 //! ## Example
+//!
 //! ```rust,no_run
 //! use poise::serenity_prelude as serenity;
 //! use shuttle_secrets::SecretStore;
@@ -71,5 +73,51 @@ impl<T, E> From<Arc<poise::Framework<T, E>>> for PoiseService<T, E> {
     }
 }
 
-/// The return type that should be returned from the [shuttle_runtime::main] function.
+/// Return type from the `[shuttle_runtime::main]` macro for a Poise-based service.
+///
+/// ## Example
+///
+/// ```rust,no_run
+/// use poise::serenity_prelude as serenity;
+/// use shuttle_secrets::SecretStore;
+/// use shuttle_poise::ShuttlePoise;
+///
+/// struct Data {} // User data, which is stored and accessible in all command invocations
+/// type Error = Box<dyn std::error::Error + Send + Sync>;
+/// type Context<'a> = poise::Context<'a, Data, Error>;
+///
+///
+/// #[poise::command(slash_command)]
+/// async fn hello(ctx: Context<'_>) -> Result<(), Error> {
+///     ctx.say("world!").await?;
+///     Ok(())
+/// }
+///
+/// #[shuttle_runtime::main]
+/// async fn poise(#[shuttle_secrets::Secrets] secret_store: SecretStore) -> ShuttlePoise<Data, Error> {
+///
+///     let discord_token = secret_store
+///         .get("DISCORD_TOKEN")
+///         .expect("'DISCORD_TOKEN' was not found");
+///
+///     let framework = poise::Framework::builder()
+///         .options(poise::FrameworkOptions {
+///             commands: vec![hello()],
+///             ..Default::default()
+///         })
+///         .token(discord_token)
+///         .intents(serenity::GatewayIntents::non_privileged())
+///         .setup(|ctx, _ready, framework| {
+///             Box::pin(async move {
+///                 poise::builtins::register_globally(ctx, &framework.options().commands).await?;
+///                 Ok(Data {})
+///             })
+///         })
+///         .build()
+///         .await
+///         .map_err(shuttle_runtime::CustomError::new)?;
+///
+///     Ok(framework.into())
+/// }
+/// ```
 pub type ShuttlePoise<T, E> = Result<PoiseService<T, E>, shuttle_runtime::Error>;

services/shuttle-rocket/src/lib.rs

@@ -12,7 +12,7 @@
 //!
 //! #[shuttle_runtime::main]
 //! async fn rocket() -> shuttle_rocket::ShuttleRocket {
-//!     let rocket = rocket::build().mount("/hello", routes![index]);
+//!     let rocket = rocket::build().mount("/", routes![index]);
 //!
 //!     Ok(rocket.into())
 //! }
@@ -59,5 +59,24 @@ impl From<rocket::Rocket<rocket::Build>> for RocketService {
     }
 }
 
-/// The return type that should be returned from the [shuttle_runtime::main] function.
+/// Return type from the `[shuttle_runtime::main]` macro for a Rocket-based service.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// use rocket::{routes, get};
+/// use shuttle_rocket::ShuttleRocket;
+///
+/// #[get("/")]
+/// fn index() -> &'static str {
+///     "Hello, world!"
+/// }
+///
+/// #[shuttle_runtime::main]
+/// async fn rocket() -> ShuttleRocket {
+///     let rocket = rocket::build().mount("/", routes![index]);
+///
+///     Ok(rocket.into())
+/// }
+/// ```
 pub type ShuttleRocket = Result<RocketService, shuttle_runtime::Error>;

services/shuttle-salvo/src/lib.rs

@@ -41,5 +41,25 @@ impl From<salvo::Router> for SalvoService {
         Self(router)
     }
 }
-/// The return type that should be returned from the [shuttle_runtime::main] function.
+
+/// Return type from the `[shuttle_runtime::main]` macro for a Salvo-based service.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// use salvo::prelude::*;
+/// use shuttle_salvo::ShuttleSalvo;
+///
+/// #[handler]
+/// async fn hello_world(res: &mut Response) {
+///     res.render(Text::Plain("Hello, world!"));
+/// }
+///
+/// #[shuttle_runtime::main]
+/// async fn salvo() -> ShuttleSalvo {
+///     let router = Router::with_path("hello").get(hello_world);
+///
+///     Ok(router.into())
+/// }
+/// ```
 pub type ShuttleSalvo = Result<SalvoService, Error>;

services/shuttle-thruster/src/lib.rs

@@ -1,5 +1,7 @@
 //! Shuttle service integration for the Thruster web framework.
+//!
 //! ## Example
+//!
 //! ```rust,no_run
 //! use thruster::{
 //!     context::basic_hyper_context::{generate_context, BasicHyperContext as Ctx, HyperRequest},
@@ -15,9 +17,9 @@
 //! #[shuttle_runtime::main]
 //! async fn thruster() -> shuttle_thruster::ShuttleThruster<HyperServer<Ctx, ()>> {
 //!     let server = HyperServer::new(
-//!         App::<HyperRequest, Ctx, ()>::create(generate_context, ()).get("/hello", m![hello]),
+//!         App::<HyperRequest, Ctx, ()>::create(generate_context, ()).get("/", m![hello]),
 //!     );
-//!     
+//!
 //!     Ok(server.into())
 //! }
 //! ```
@@ -49,5 +51,29 @@ where
         Self(router)
     }
 }
-/// The return type that should be returned from the [shuttle_runtime::main] function.
+
+/// The return type of the [shuttle_runtime::main] function for the Thruster service.
+///
+/// ## Example
+///
+/// ```rust,no_run
+/// use shuttle_thruster::ShuttleThruster;
+/// use thruster::{
+///     context::basic_hyper_context::{generate_context, BasicHyperContext as Ctx, HyperRequest},
+///     m, middleware_fn, App, HyperServer, MiddlewareNext, MiddlewareResult, ThrusterServer,
+/// };
+///
+/// #[middleware_fn]
+/// async fn hello(mut context: Ctx, _next: MiddlewareNext<Ctx>) -> MiddlewareResult<Ctx> {
+///     context.body("Hello, World!");
+///     Ok(context)
+/// }
+///
+/// #[shuttle_runtime::main]
+/// async fn thruster() -> ShuttleThruster<HyperServer<Ctx, ()>> {
+///     Ok(HyperServer::new(
+///         App::<HyperRequest, Ctx, ()>::create(generate_context, ()).get("/", m![hello]),
+///     ).into())
+/// }
+/// ```
 pub type ShuttleThruster<T> = Result<ThrusterService<T>, Error>;

services/shuttle-tide/src/lib.rs

@@ -8,7 +8,7 @@
 //!     let mut app = tide::new();
 //!     app.with(tide::log::LogMiddleware::new());
 //!
-//!     app.at("/hello").get(|_| async { Ok("Hello, world!") });
+//!     app.at("/").get(|_| async { Ok("Hello, world!") });
 //!
 //!     Ok(app.into())
 //! }

services/shuttle-warp/src/lib.rs

@@ -1,5 +1,7 @@
 //! Shuttle service integration for the Warp web framework.
+//!
 //! ## Example
+//!
 //! ```rust,no_run
 //! use warp::Filter;
 //! use warp::Reply;
@@ -49,5 +51,19 @@ impl<T> Deref for WarpService<T> {
     }
 }
 
-/// The return type that should be returned from the [shuttle_runtime::main] function.
+/// The return type of the [shuttle_runtime::main] function for the Warp service.
+///
+/// ## Example
+///
+/// ```rust,no_run
+/// use shuttle_warp::ShuttleWarp;
+/// use warp::Filter;
+/// use warp::Reply;
+///
+/// #[shuttle_runtime::main]
+/// async fn warp() -> ShuttleWarp<(impl Reply,)> {
+///     let route = warp::any().map(|| "Hello, World");
+///     Ok(route.boxed().into())
+/// }
+/// ```
 pub type ShuttleWarp<T> = Result<WarpService<warp::filters::BoxedFilter<T>>, Error>;