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]]
name = "ratelimiting"
required-features = ["ratelimiting"]
[package.metadata.docs.rs]
rustc-args = ["--cfg", "docsrs"]

View File

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

View File

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

View File

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

View File

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

View File

@ -209,6 +209,7 @@ impl Request {
}
#[cfg(feature="scgi_srv")]
#[doc(cfg(feature = "scgi_srv"))]
/// View any headers sent by the SCGI client
///
/// 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")]
#[doc(cfg(feature = "user_management"))]
/// Attempt to determine the user who sent this request
///
/// 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")]
#[doc(cfg(feature = "user_management"))]
/// Expose the server's UserManager
///
/// Can be used to query users, or directly access the database

View File

@ -23,6 +23,7 @@ mod manager;
#[cfg(feature = "user_management_routes")]
mod routes;
#[cfg(feature = "user_management_routes")]
#[doc(cfg(feature = "user_management_routes"))]
pub use routes::UserManagementRoutes;
pub use manager::UserManager;
pub use user::User;
@ -71,6 +72,7 @@ pub enum UserManagerError {
DeserializeUtf8Error(std::str::Utf8Error),
#[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
/// There was an error hashing or checking the user's password.
///
/// 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")]
#[doc(cfg(feature = "user_management_advanced"))]
impl From<argon2::Error> for UserManagerError {
fn from(error: argon2::Error) -> Self {
Self::Argon2Error(error)
@ -117,6 +120,7 @@ impl std::error::Error for UserManagerError {
Self::DeserializeBincodeError(e) => Some(e),
Self::DeserializeUtf8Error(e) => Some(e),
#[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
Self::Argon2Error(e) => Some(e),
_ => None
}
@ -139,6 +143,7 @@ impl std::fmt::Display for UserManagerError {
Self::DeserializeUtf8Error(e) =>
write!(f, "Recieved invalid UTF-8 from database, possible corruption: {}", e),
#[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
Self::Argon2Error(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")]
#[doc(cfg(feature = "user_management_advanced"))]
/// Attach this certificate to an existing user
///
/// 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")]
#[doc(cfg(feature = "user_management_advanced"))]
/// Check a password against the user's password hash
///
/// # Errors
@ -274,6 +276,7 @@ impl<UserData: Serialize + DeserializeOwned> RegisteredUser<UserData> {
}
#[cfg(feature = "user_management_advanced")]
#[doc(cfg(feature = "user_management_advanced"))]
/// Set's the password for this user
///
/// 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")]
#[doc(cfg(feature = "user_management_advanced"))]
/// Check if the user has a password set
///
/// 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;
#[cfg(feature="serve_dir")]
#[doc(cfg(feature = "serve_dir"))]
pub async fn serve_file<P: AsRef<Path>>(path: P, mime: &str) -> Response {
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")]
#[doc(cfg(feature = "serve_dir"))]
pub async fn serve_dir<D: AsRef<Path>, P: AsRef<Path>>(dir: D, virtual_path: &[P]) -> Response {
debug!("Dir: {}", dir.as_ref().display());
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")]
#[doc(cfg(feature = "serve_dir"))]
pub fn guess_mime_from_path<P: AsRef<Path>>(path: P) -> &'static str {
let path = path.as_ref();
let extension = path.extension().and_then(|s| s.to_str());