docs(jsdoc): align library and utility JSDoc style ✏️

- Add @description clauses across shared type exports in Types.ts
- Add @description lines across validation helpers under src/utils
- Refresh entry-point mailer JSDoc blocks in src/index.ts
- Shorten overlong interface briefs to skill word-limit constraints
- Standardize dotted sentence style on JSDoc brief and description lines

Author: NeaByteLab

src/Types.ts

@@ -1,5 +1,6 @@
 /**
  * Calendar event invitation data.
+ * @description Defines calendar payload fields for event invites.
  */
 export interface CalendarInvite {
   /** Unique identifier for the calendar event */
@@ -24,6 +25,7 @@ export interface CalendarInvite {
 
 /**
  * Email attachment data.
+ * @description Defines attachment payload for SMTP MIME messages.
  */
 export interface EmailAttachment {
   /** Name of the attached file */
@@ -38,6 +40,7 @@ export interface EmailAttachment {
 
 /**
  * Email contact information.
+ * @description Describes email address and optional display name.
  */
 export interface EmailContact {
   /** Optional display name for the contact */
@@ -48,6 +51,7 @@ export interface EmailContact {
 
 /**
  * Complete email message structure.
+ * @description Defines sender recipients body and message options.
  */
 export interface EmailMessage {
   /** Sender email address or contact */
@@ -77,16 +81,19 @@ export interface EmailMessage {
 }
 
 /**
- * Email recipient type that can be a string, EmailContact object, or array of either.
+ * Email recipient type.
+ * @description Allows string object or array recipient formats.
  */
 export type EmailRecipient = string | EmailContact | (string | EmailContact)[]
 
 /**
  * Email sender interface.
+ * @description Defines async message send capability contract.
  */
 export interface EmailSender {
   /**
    * Sends an email message.
+   * @description Sends one message and returns SMTP result data.
    * @param message - The email message to send
    * @returns Structured SMTP delivery result
    * @throws {Error} When message sending fails
@@ -96,10 +103,12 @@ export interface EmailSender {
 
 /**
  * Email service interface.
+ * @description Defines factory for creating SMTP senders.
  */
 export interface EmailService {
   /**
-   * Creates an email transporter with SMTP configuration.
+   * Create email transporter.
+   * @description Builds sender from SMTP connection configuration.
    * @param config - SMTP connection configuration
    * @returns Email sender instance
    */
@@ -108,6 +117,7 @@ export interface EmailService {
 
 /**
  * Embedded image attachment.
+ * @description Extends attachment with CID and disposition fields.
  */
 export interface EmbeddedImage extends EmailAttachment {
   /** Content-ID for referencing in HTML */
@@ -118,6 +128,7 @@ export interface EmbeddedImage extends EmailAttachment {
 
 /**
  * Processed email contact.
+ * @description Represents normalized address for SMTP processing.
  */
 export interface ProcessedContact {
   /** Email address */
@@ -154,6 +165,7 @@ export interface SmtpPasswordAuthCredential extends SmtpAuthBase<'password'> {
 
 /**
  * SMTP connection configuration.
+ * @description Defines host port auth DKIM and pooling options.
  */
 export interface SmtpConnectionConfig {
   /** SMTP server hostname */
@@ -172,6 +184,7 @@ export interface SmtpConnectionConfig {
 
 /**
  * SMTP connection state.
+ * @description Holds active sockets and SMTP config reference.
  */
 export interface SmtpConnectionState {
   /** Raw TCP connection */

src/index.ts

@@ -3,11 +3,13 @@ import * as SMTP from '@smtp/index.ts'
 import * as Utils from '@utils/index.ts'
 
 /**
- * Main email service for sending messages via SMTP.
+ * Main email service.
+ * @description Exposes transporter factory for SMTP message sending.
  */
 export const mailer: Types.EmailService = {
   /**
-   * Creates an email transporter with SMTP configuration.
+   * Create email transporter.
+   * @description Validates config and returns sender abstraction.
    * @param config - SMTP connection configuration
    * @returns Email sender instance
    * @throws {Error} When configuration is invalid
@@ -19,7 +21,8 @@ export const mailer: Types.EmailService = {
 }
 
 /**
- * Creates email transporter instance.
+ * Create transporter instance.
+ * @description Builds sender with pooled or direct clients.
  * @param config - SMTP connection configuration
  * @returns Email sender implementation
  */
@@ -95,7 +98,7 @@ class SmtpClientPool {
 
   /**
    * Acquire pooled SMTP client.
-   * @description Returns an idle client or creates one.
+   * @description Returns idle client or creates new one.
    * @returns Available SMTP client instance
    */
   async acquireClient(): Promise<SMTP.SmtpClient> {
@@ -122,7 +125,7 @@ class SmtpClientPool {
 
   /**
    * Release pooled SMTP client.
-   * @description Marks client idle or hands off to waiting sender.
+   * @description Marks idle or hands off waiting sender.
    * @param client - SMTP client instance to release
    */
   releaseClient(client: SMTP.SmtpClient): void {
@@ -155,8 +158,8 @@ class SmtpClientPool {
   }
 
   /**
-   * Increment pooled client usage count.
-   * @description Tracks sent message count for recycle policy.
+   * Increment client usage count.
+   * @description Tracks message count for recycle policy.
    * @param client - SMTP client instance to count
    */
   markMessageProcessed(client: SMTP.SmtpClient): void {
@@ -166,13 +169,13 @@ class SmtpClientPool {
 }
 
 /**
- * Default export of the email service.
- * @description Main entry point for the Deno-Mailer library.
+ * Default mailer export.
+ * @description Provides main library entry for SMTP sending.
  */
 export default mailer
 
 /**
- * Re-exports all type definitions.
- * @description Provides access to all TypeScript interfaces and types.
+ * Re-export all types.
+ * @description Exposes shared interfaces and type aliases.
  */
 export type * from '@app/Types.ts'

src/utils/Attachment.ts

@@ -2,6 +2,7 @@ import type * as Types from '@app/Types.ts'
 
 /**
  * Validates email attachment data.
+ * @description Checks filename content encoding fields and types.
  * @param attachment - Attachment to validate
  * @throws {Error} When attachment validation fails
  */
@@ -40,6 +41,7 @@ export function isValidAttachment(attachment: Types.EmailAttachment): void {
 
 /**
  * Validates embedded image attachment data.
+ * @description Reuses attachment checks and validates CID format.
  * @param attachment - Embedded attachment to validate
  * @throws {Error} When embedded attachment validation fails
  */

src/utils/Config.ts

@@ -2,6 +2,7 @@ import type * as Types from '@app/Types.ts'
 
 /**
  * Validates SMTP connection configuration.
+ * @description Runs nested checks for host port auth and options.
  * @param config - SMTP configuration to validate
  * @throws {Error} When configuration validation fails
  */
@@ -19,6 +20,7 @@ export function isValidConfig(config: Types.SmtpConnectionConfig): void {
 
 /**
  * Validates SMTP authentication credentials.
+ * @description Checks password and oauth2 shapes and lengths.
  * @param auth - Authentication credentials to validate
  * @throws {Error} When authentication validation fails
  */
@@ -54,6 +56,7 @@ function validateAuth(auth: Types.SmtpAuthCredential | undefined): void {
 
 /**
  * Validates SMTP DKIM configuration.
+ * @description Ensures domain selector and private key exist.
  * @param dkim - DKIM settings to validate
  * @throws {Error} When DKIM validation fails
  */
@@ -74,6 +77,7 @@ function validateDkim(dkim: Types.SmtpDkimConfig | undefined): void {
 
 /**
  * Validates SMTP host configuration.
+ * @description Checks host type length and non-empty value.
  * @param host - Host string to validate
  * @throws {Error} When host validation fails
  */
@@ -94,6 +98,7 @@ function validateHost(host: string): void {
 
 /**
  * Validates SMTP pool configuration.
+ * @description Validates pool booleans and numeric constraints.
  * @param pool - Pool settings to validate
  * @throws {Error} When pool validation fails
  */
@@ -126,6 +131,7 @@ function validatePool(pool: Types.SmtpPoolConfig | boolean | undefined): void {
 
 /**
  * Validates SMTP port configuration.
+ * @description Checks port type integer and allowed range.
  * @param port - Port number to validate
  * @throws {Error} When port validation fails
  */
@@ -146,6 +152,7 @@ function validatePort(port: number): void {
 
 /**
  * Validates SMTP secure configuration.
+ * @description Ensures secure flag is boolean type only.
  * @param secure - Secure flag to validate
  * @throws {Error} When secure validation fails
  */

src/utils/Content.ts

@@ -1,5 +1,6 @@
 /**
  * Generates unique Content-ID for embedded attachments.
+ * @description Builds random bytes timestamp and domain mailbox id.
  * @param domain - Domain name for Content-ID (defaults to 'deno-mailer.local')
  * @returns Generated Content-ID string
  */
@@ -15,6 +16,7 @@ export function generateContentId(domain = 'deno-mailer.local'): string {
 
 /**
  * Validates Content-ID format.
+ * @description Checks angle brackets at symbol and length bounds.
  * @param cid - Content-ID string to validate
  * @throws {Error} When Content-ID validation fails
  */

src/utils/Email.ts

@@ -1,5 +1,6 @@
 /**
  * Validates email address format.
+ * @description Checks local part domain labels and basic syntax.
  * @param email - Email address string to validate
  * @throws {Error} When email validation fails
  */