Add documentation to public members (#205)

Author: Hinton

crates/bitwarden-cli/src/color.rs

@@ -1,9 +1,13 @@
 use clap::ValueEnum;
 
+/// Color configuration for the CLI
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum, Debug)]
 pub enum Color {
+    /// Force colors off
     No,
+    /// Force colors on
     Yes,
+    /// Automatically detect if colors are supported in the terminal.
     Auto,
 }
 

crates/bitwarden-core/Cargo.toml

@@ -19,8 +19,8 @@ internal = ["dep:zxcvbn"]
 no-memory-hardening = [
     "bitwarden-crypto/no-memory-hardening"
 ] # Disable memory hardening features
-uniffi = ["bitwarden-crypto/uniffi", "dep:uniffi"] # Uniffi bindings
 secrets = [] # Secrets manager API
+uniffi = ["bitwarden-crypto/uniffi", "dep:uniffi"] # Uniffi bindings
 wasm = [
     "bitwarden-error/wasm",
     "dep:wasm-bindgen",

crates/bitwarden-core/README.md

@@ -1,7 +1,17 @@
 # Bitwarden Core
 
-Contains core functionality used by the feature crates.
+Contains core functionality used by the feature crates. For an introduction to the Bitwarden SDK and
+the `bitwarden-core` create please refer to the
+[SDK Architecture](https://contributing.bitwarden.com/architecture/sdk/) documentation.
 
 <div class="warning">
 Generally you should <b>not</b> find yourself needing to edit this crate! When possible, please use the feature crates instead.
 </div>
+
+## Features
+
+- `internal` - Internal unstable APIs that should only be consumed by internal Bitwarden clients.
+- `no-memory-hardening` - Disables `bitwarden-crypto` memory hardening.
+- `secrets` - Secrets Manager specific functionality.
+- `uniffi` - Mobile bindings.
+- `wasm` - WebAssembly bindings.

crates/bitwarden-core/src/admin_console/mod.rs

@@ -1,3 +1,7 @@
+//! Admin console module for Bitwarden Core.
+//!
+//! Contains policies.
+
 mod policy;
 
 pub use policy::Policy;

crates/bitwarden-core/src/admin_console/policy.rs

@@ -8,6 +8,7 @@ use uuid::Uuid;
 
 use crate::{require, MissingFieldError};
 
+/// Represents a policy that can be applied to an organization.
 #[derive(Serialize, Deserialize, Debug, JsonSchema)]
 pub struct Policy {
     id: Uuid,
@@ -20,20 +21,30 @@ pub struct Policy {
 #[derive(Serialize_repr, Deserialize_repr, Debug, JsonSchema)]
 #[repr(u8)]
 pub enum PolicyType {
-    TwoFactorAuthentication = 0, // Requires users to have 2fa enabled
-    MasterPassword = 1,          // Sets minimum requirements for master password complexity
-    PasswordGenerator = 2,       /* Sets minimum requirements/default type for generated
-                                  * passwords/passphrases */
-    SingleOrg = 3,         // Allows users to only be apart of one organization
-    RequireSso = 4,        // Requires users to authenticate with SSO
-    PersonalOwnership = 5, // Disables personal vault ownership for adding/cloning items
-    DisableSend = 6,       // Disables the ability to create and edit Bitwarden Sends
-    SendOptions = 7,       // Sets restrictions or defaults for Bitwarden Sends
-    ResetPassword = 8,     /* Allows orgs to use reset password : also can enable
-                            * auto-enrollment during invite flow */
-    MaximumVaultTimeout = 9,         // Sets the maximum allowed vault timeout
-    DisablePersonalVaultExport = 10, // Disable personal vault export
-    ActivateAutofill = 11,           // Activates autofill with page load on the browser extension
+    /// Requires users to have 2fa enabled
+    TwoFactorAuthentication = 0,
+    /// Sets minimum requirements for master password complexity
+    MasterPassword = 1,
+    /// Sets minimum requirements/default type for generated passwords/passphrases
+    PasswordGenerator = 2,
+    /// Allows users to only be apart of one organization
+    SingleOrg = 3,
+    /// Requires users to authenticate with SSO
+    RequireSso = 4,
+    /// Disables personal vault ownership for adding/cloning items
+    PersonalOwnership = 5,
+    /// Disables the ability to create and edit Bitwarden Sends
+    DisableSend = 6,
+    /// Sets restrictions or defaults for Bitwarden Sends
+    SendOptions = 7,
+    /// Allows orgs to use reset password : also can enable auto-enrollment during invite flow
+    ResetPassword = 8,
+    /// Sets the maximum allowed vault timeout
+    MaximumVaultTimeout = 9,
+    /// Disable personal vault export
+    DisablePersonalVaultExport = 10,
+    /// Activates autofill with page load on the browser extension
+    ActivateAutofill = 11,
     AutomaticAppLogIn = 12,
     FreeFamiliesSponsorshipPolicy = 13,
     RemoveUnlockWithPin = 14,

crates/bitwarden-core/src/auth/access_token.rs

@@ -8,6 +8,7 @@ use zeroize::Zeroizing;
 
 use crate::util::STANDARD_INDIFFERENT;
 
+#[allow(missing_docs)]
 #[derive(Debug, Error)]
 pub enum AccessTokenInvalidError {
     #[error("Doesn't contain a decryption key")]
@@ -26,9 +27,13 @@ pub enum AccessTokenInvalidError {
     InvalidBase64Length { expected: usize, got: usize },
 }
 
+/// Access Token
 pub struct AccessToken {
+    /// The ID of the access token
     pub access_token_id: Uuid,
+    /// The client secret
     pub client_secret: String,
+    /// The encryption key used to decrypt a payload to retrieve the organization key.
     pub encryption_key: SymmetricCryptoKey,
 }
 

crates/bitwarden-core/src/auth/auth_request.rs

@@ -11,6 +11,7 @@ use thiserror::Error;
 use crate::client::encryption_settings::EncryptionSettingsError;
 use crate::{key_management::SymmetricKeyId, Client, VaultLockedError};
 
+/// Response for `new_auth_request`.
 #[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
 pub struct AuthRequestResponse {
     /// Base64 encoded private key
@@ -75,6 +76,7 @@ pub(crate) fn auth_request_decrypt_master_key(
     Ok(master_key.decrypt_user_key(user_key)?)
 }
 
+#[allow(missing_docs)]
 #[derive(Debug, Error)]
 pub enum ApproveAuthRequestError {
     #[error(transparent)]

crates/bitwarden-core/src/auth/jwt_token.rs

@@ -12,13 +12,20 @@ use thiserror::Error;
 /// TODO: We need to expand this to support user based JWT tokens.
 #[derive(serde::Deserialize)]
 pub struct JwtToken {
+    /// Expiration Time.
     pub exp: u64,
+    /// Subject.
     pub sub: String,
+    /// User's email.
     pub email: Option<String>,
+    /// Used by Service Accounts to denote the organization.
     pub organization: Option<String>,
+    /// The scopes the token has access to.
     pub scope: Vec<String>,
 }
 
+/// Error when parsing JWT tokens.
+#[allow(missing_docs)]
 #[derive(Debug, Error)]
 pub enum JwtTokenParseError {
     #[error("JWT token parse error: {0}")]

crates/bitwarden-core/src/auth/mod.rs

@@ -1,3 +1,7 @@
+//! Authentication module
+//!
+//! Contains all the authentication related functionality for registering and logging in.
+
 use thiserror::Error;
 
 use crate::{NotAuthenticatedError, VaultLockedError, WrongPasswordError};
@@ -36,6 +40,8 @@ mod key_connector;
 #[cfg(feature = "internal")]
 pub use key_connector::KeyConnectorResponse;
 
+/// Error for authentication related operations
+#[allow(missing_docs)]
 #[derive(Debug, Error)]
 pub enum AuthValidateError {
     #[error(transparent)]

crates/bitwarden-core/src/error.rs

@@ -25,6 +25,8 @@ macro_rules! impl_bitwarden_error {
     };
 }
 
+/// Errors from performing network requests.
+#[allow(missing_docs)]
 #[derive(Debug, Error)]
 pub enum ApiError {
     #[error(transparent)]
@@ -41,22 +43,27 @@ pub enum ApiError {
 impl_bitwarden_error!(ApiApisError, ApiError);
 impl_bitwarden_error!(IdentityError, ApiError);
 
+/// Client is not authenticated or the session has expired.
 #[derive(Debug, Error)]
 #[error("The client is not authenticated or the session has expired")]
 pub struct NotAuthenticatedError;
 
+/// Missing required field.
 #[derive(Debug, Error)]
 #[error("The response received was missing a required field: {0}")]
 pub struct MissingFieldError(pub &'static str);
 
+/// Client vault is locked.
 #[derive(Debug, Error)]
 #[error("The client vault is locked and needs to be unlocked before use")]
 pub struct VaultLockedError;
 
+/// Wrong password.
 #[derive(Debug, thiserror::Error)]
 #[error("Wrong password")]
 pub struct WrongPasswordError;
 
+/// Missing private key.
 #[derive(Debug, thiserror::Error)]
 #[error("Missing private key")]
 pub struct MissingPrivateKeyError;