Added unstable doc attributes to generate fancy docs

This commit is contained in:
Emi Tatsuo 2020-12-11 14:28:30 -05:00
parent 2501c9021a
commit 6a7a65d929
Signed by: Emi
GPG key ID: 68FAB2E2E6DFC98B
9 changed files with 34 additions and 0 deletions

View file

@ -58,3 +58,6 @@ required-features = ["serve_dir"]
[[example]] [[example]]
name = "ratelimiting" name = "ratelimiting"
required-features = ["ratelimiting"] required-features = ["ratelimiting"]
[package.metadata.docs.rs]
rustc-args = ["--cfg", "docsrs"]

View file

@ -26,6 +26,7 @@ use rustls::*;
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
#[cfg(feature = "certgen")] #[cfg(feature = "certgen")]
#[cfg_attr(docsrs, doc(cfg(feature = "certgen")))]
/// The mode to use for determining the domains to use for a new certificate. /// The mode to use for determining the domains to use for a new certificate.
/// ///
/// Used to configure a [`Server`] using [`set_certificate_generation_mode()`] /// Used to configure a [`Server`] using [`set_certificate_generation_mode()`]
@ -45,6 +46,7 @@ pub enum CertGenMode {
} }
#[cfg(feature = "certgen")] #[cfg(feature = "certgen")]
#[cfg_attr(docsrs, doc(cfg(feature = "certgen")))]
impl CertGenMode { impl CertGenMode {
/// Generate a new self-signed certificate /// Generate a new self-signed certificate
/// ///

View file

@ -56,6 +56,7 @@ pub enum Handler {
StaticHandler(Response), StaticHandler(Response),
#[cfg(feature = "serve_dir")] #[cfg(feature = "serve_dir")]
#[cfg_attr(docsrs, doc(cfg(feature = "serve_dir")))]
/// A handler that serves a directory, including a directory listing /// A handler that serves a directory, including a directory listing
/// ///
/// Most often created with [`From<PathBuf>`] /// Most often created with [`From<PathBuf>`]
@ -208,6 +209,7 @@ impl From<&Document> for Handler {
} }
#[cfg(feature = "serve_dir")] #[cfg(feature = "serve_dir")]
#[doc(cfg(feature = "serve_dir"))]
impl From<PathBuf> for Handler { impl From<PathBuf> for Handler {
/// Serve files from a directory /// Serve files from a directory
/// ///

View file

@ -237,6 +237,7 @@ pub mod routing;
#[cfg(feature = "ratelimiting")] #[cfg(feature = "ratelimiting")]
mod ratelimiting; mod ratelimiting;
#[cfg(feature = "user_management")] #[cfg(feature = "user_management")]
#[doc(cfg(feature = "user_management"))]
pub mod user_management; pub mod user_management;
#[cfg(feature = "gemini_srv")] #[cfg(feature = "gemini_srv")]
mod cert; mod cert;
@ -244,6 +245,7 @@ mod cert;
#[cfg(feature="user_management")] #[cfg(feature="user_management")]
use user_management::UserManager; use user_management::UserManager;
#[cfg(feature = "certgen")] #[cfg(feature = "certgen")]
#[doc(cfg(feature = "certgen"))]
pub use cert::CertGenMode; pub use cert::CertGenMode;
pub use uriparse::URIReference; pub use uriparse::URIReference;
@ -708,6 +710,7 @@ impl Server {
} }
#[cfg(feature="user_management")] #[cfg(feature="user_management")]
#[doc(cfg(feature = "user_management"))]
/// Sets the directory to store user data in /// Sets the directory to store user data in
/// ///
/// This will only be used if a database is not provided with [`set_database()`]. /// This will only be used if a database is not provided with [`set_database()`].
@ -721,6 +724,7 @@ impl Server {
} }
#[cfg(feature="user_management")] #[cfg(feature="user_management")]
#[doc(cfg(feature = "user_management"))]
/// Sets a specific database to use /// Sets a specific database to use
/// ///
/// This opens to trees within the database, both namespaced to avoid collisions. /// This opens to trees within the database, both namespaced to avoid collisions.
@ -735,6 +739,7 @@ impl Server {
} }
#[cfg(feature="certgen")] #[cfg(feature="certgen")]
#[doc(cfg(feature = "certgen"))]
/// Determine where certificate config comes from, if generation is required /// Determine where certificate config comes from, if generation is required
/// ///
/// If a certificate & keyfile are not available on the provided path, they can be /// If a certificate & keyfile are not available on the provided path, they can be
@ -747,6 +752,7 @@ impl Server {
} }
#[cfg(feature = "gemini_srv")] #[cfg(feature = "gemini_srv")]
#[doc(cfg(feature = "gemini_srv"))]
/// Sets the directory that kochab should look for TLS certs and keys into /// Sets the directory that kochab should look for TLS certs and keys into
/// ///
/// Northstar will look for files called `cert.pem` and `key.pem` in the provided /// Northstar will look for files called `cert.pem` and `key.pem` in the provided
@ -763,6 +769,7 @@ impl Server {
} }
#[cfg(feature = "gemini_srv")] #[cfg(feature = "gemini_srv")]
#[doc(cfg(feature = "gemini_srv"))]
/// Set the path to the TLS certificate kochab will use /// Set the path to the TLS certificate kochab will use
/// ///
/// This defaults to `cert/cert.pem`. /// This defaults to `cert/cert.pem`.
@ -775,6 +782,7 @@ impl Server {
} }
#[cfg(feature = "gemini_srv")] #[cfg(feature = "gemini_srv")]
#[doc(cfg(feature = "gemini_srv"))]
/// Set the path to the ertificate key kochab will use /// Set the path to the ertificate key kochab will use
/// ///
/// This defaults to `cert/key.pem`. /// This defaults to `cert/key.pem`.
@ -860,6 +868,7 @@ impl Server {
} }
#[cfg(feature="ratelimiting")] #[cfg(feature="ratelimiting")]
#[doc(cfg(feature = "ratelimiting"))]
/// Add a rate limit to a route /// Add a rate limit to a route
/// ///
/// The server will allow at most `burst` connections to any endpoints under this /// The server will allow at most `burst` connections to any endpoints under this
@ -983,6 +992,7 @@ impl Server {
} }
#[cfg(feature = "scgi_srv")] #[cfg(feature = "scgi_srv")]
#[doc(cfg(feature = "scgi_srv"))]
/// Start serving requests on a given unix socket /// Start serving requests on a given unix socket
/// ///
/// Requires an address in the form of a path to bind to. This is only available when /// Requires an address in the form of a path to bind to. This is only available when

View file

@ -27,6 +27,7 @@ pub enum Body {
impl Body { impl Body {
/// Called by [`Response::rewrite_all`] /// Called by [`Response::rewrite_all`]
#[cfg(feature="scgi_srv")] #[cfg(feature="scgi_srv")]
#[cfg_attr(docsrs, doc(cfg(feature = "scgi_srv")))]
pub (crate) async fn rewrite_all(&mut self, based_on: &crate::Request) -> std::io::Result<bool> { pub (crate) async fn rewrite_all(&mut self, based_on: &crate::Request) -> std::io::Result<bool> {
let bytes = match self { let bytes = match self {
Self::Bytes(bytes) => { Self::Bytes(bytes) => {
@ -101,6 +102,7 @@ impl<'a> From<&'a str> for Body {
} }
#[cfg(feature="serve_dir")] #[cfg(feature="serve_dir")]
#[cfg_attr(docsrs, doc(cfg(feature = "serve_dir")))]
impl From<File> for Body { impl From<File> for Body {
fn from(file: File) -> Self { fn from(file: File) -> Self {
Self::Reader(Box::new(file)) Self::Reader(Box::new(file))

View file

@ -209,6 +209,7 @@ impl Request {
} }
#[cfg(feature="scgi_srv")] #[cfg(feature="scgi_srv")]
#[doc(cfg(feature = "scgi_srv"))]
/// View any headers sent by the SCGI client /// View any headers sent by the SCGI client
/// ///
/// When an SCGI client delivers a request (e.g. when your gemini server sends a /// When an SCGI client delivers a request (e.g. when your gemini server sends a
@ -252,6 +253,7 @@ impl Request {
} }
#[cfg(feature="user_management")] #[cfg(feature="user_management")]
#[doc(cfg(feature = "user_management"))]
/// Attempt to determine the user who sent this request /// Attempt to determine the user who sent this request
/// ///
/// May return a variant depending on if the client used a client certificate, and if /// May return a variant depending on if the client used a client certificate, and if
@ -264,6 +266,7 @@ impl Request {
} }
#[cfg(feature="user_management")] #[cfg(feature="user_management")]
#[doc(cfg(feature = "user_management"))]
/// Expose the server's UserManager /// Expose the server's UserManager
/// ///
/// Can be used to query users, or directly access the database /// Can be used to query users, or directly access the database

View file

@ -23,6 +23,7 @@ mod manager;
#[cfg(feature = "user_management_routes")] #[cfg(feature = "user_management_routes")]
mod routes; mod routes;
#[cfg(feature = "user_management_routes")] #[cfg(feature = "user_management_routes")]
#[doc(cfg(feature = "user_management_routes"))]
pub use routes::UserManagementRoutes; pub use routes::UserManagementRoutes;
pub use manager::UserManager; pub use manager::UserManager;
pub use user::User; pub use user::User;
@ -71,6 +72,7 @@ pub enum UserManagerError {
DeserializeUtf8Error(std::str::Utf8Error), DeserializeUtf8Error(std::str::Utf8Error),
#[cfg(feature = "user_management_advanced")] #[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
/// There was an error hashing or checking the user's password. /// There was an error hashing or checking the user's password.
/// ///
/// This likely indicates database corruption, and should be handled in the same way /// This likely indicates database corruption, and should be handled in the same way
@ -103,6 +105,7 @@ impl From<std::str::Utf8Error> for UserManagerError {
} }
#[cfg(feature = "user_management_advanced")] #[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
impl From<argon2::Error> for UserManagerError { impl From<argon2::Error> for UserManagerError {
fn from(error: argon2::Error) -> Self { fn from(error: argon2::Error) -> Self {
Self::Argon2Error(error) Self::Argon2Error(error)
@ -117,6 +120,7 @@ impl std::error::Error for UserManagerError {
Self::DeserializeBincodeError(e) => Some(e), Self::DeserializeBincodeError(e) => Some(e),
Self::DeserializeUtf8Error(e) => Some(e), Self::DeserializeUtf8Error(e) => Some(e),
#[cfg(feature = "user_management_advanced")] #[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
Self::Argon2Error(e) => Some(e), Self::Argon2Error(e) => Some(e),
_ => None _ => None
} }
@ -139,6 +143,7 @@ impl std::fmt::Display for UserManagerError {
Self::DeserializeUtf8Error(e) => Self::DeserializeUtf8Error(e) =>
write!(f, "Recieved invalid UTF-8 from database, possible corruption: {}", e), write!(f, "Recieved invalid UTF-8 from database, possible corruption: {}", e),
#[cfg(feature = "user_management_advanced")] #[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
Self::Argon2Error(e) => Self::Argon2Error(e) =>
write!(f, "Argon2 Error, likely malformed password hash, possible database corruption: {}", e), write!(f, "Argon2 Error, likely malformed password hash, possible database corruption: {}", e),
} }

View file

@ -141,6 +141,7 @@ impl NotSignedInUser {
} }
#[cfg(feature = "user_management_advanced")] #[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
/// Attach this certificate to an existing user /// Attach this certificate to an existing user
/// ///
/// Try to add this certificate to another user using a username and password. If /// Try to add this certificate to another user using a username and password. If
@ -252,6 +253,7 @@ impl<UserData: Serialize + DeserializeOwned> RegisteredUser<UserData> {
} }
#[cfg(feature = "user_management_advanced")] #[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
/// Check a password against the user's password hash /// Check a password against the user's password hash
/// ///
/// # Errors /// # Errors
@ -274,6 +276,7 @@ impl<UserData: Serialize + DeserializeOwned> RegisteredUser<UserData> {
} }
#[cfg(feature = "user_management_advanced")] #[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
/// Set's the password for this user /// Set's the password for this user
/// ///
/// By default, users have no password, meaning the cannot add any certificates beyond /// By default, users have no password, meaning the cannot add any certificates beyond
@ -364,6 +367,7 @@ impl<UserData: Serialize + DeserializeOwned> RegisteredUser<UserData> {
} }
#[cfg(feature = "user_management_advanced")] #[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
/// Check if the user has a password set /// Check if the user has a password set
/// ///
/// Since authentication is done using client certificates, users aren't required to /// Since authentication is done using client certificates, users aren't required to

View file

@ -16,6 +16,7 @@ use crate::types::{Document, document::HeadingLevel::*};
use crate::types::Response; use crate::types::Response;
#[cfg(feature="serve_dir")] #[cfg(feature="serve_dir")]
#[doc(cfg(feature = "serve_dir"))]
pub async fn serve_file<P: AsRef<Path>>(path: P, mime: &str) -> Response { pub async fn serve_file<P: AsRef<Path>>(path: P, mime: &str) -> Response {
let path = path.as_ref(); let path = path.as_ref();
@ -34,6 +35,7 @@ pub async fn serve_file<P: AsRef<Path>>(path: P, mime: &str) -> Response {
} }
#[cfg(feature="serve_dir")] #[cfg(feature="serve_dir")]
#[doc(cfg(feature = "serve_dir"))]
pub async fn serve_dir<D: AsRef<Path>, P: AsRef<Path>>(dir: D, virtual_path: &[P]) -> Response { pub async fn serve_dir<D: AsRef<Path>, P: AsRef<Path>>(dir: D, virtual_path: &[P]) -> Response {
debug!("Dir: {}", dir.as_ref().display()); debug!("Dir: {}", dir.as_ref().display());
let dir = dir.as_ref(); let dir = dir.as_ref();
@ -129,6 +131,7 @@ async fn serve_dir_listing<P: AsRef<Path>, B: AsRef<Path>>(path: P, virtual_path
} }
#[cfg(feature="serve_dir")] #[cfg(feature="serve_dir")]
#[doc(cfg(feature = "serve_dir"))]
pub fn guess_mime_from_path<P: AsRef<Path>>(path: P) -> &'static str { pub fn guess_mime_from_path<P: AsRef<Path>>(path: P) -> &'static str {
let path = path.as_ref(); let path = path.as_ref();
let extension = path.extension().and_then(|s| s.to_str()); let extension = path.extension().and_then(|s| s.to_str());