Revision of the GoDoc documentation #324
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Extended documentation for each SMTP AUTH type including security considerations, relevant specifications, and the context for usage. Updated error descriptions for consistency and clarity. This enhances readability and provides better guidance for developers.
Updated the comment for SMTPAuthType to more clearly explain its purpose as a type wrapper for SMTP authentication mechanisms. This improves code readability and helps future developers understand the type's function.
Streamlined comments and documentation in `b64linebreaker.go` for better readability and consistency. Improved descriptions of the Base64LineBreaker and its methods to ensure clarity on functionality.
Changed the URLs for RFC 4954 and RFC 4616 from plain text to HTML formats for improved readability and consistency. This adjustment does not affect the functionality but enhances the documentation quality.
Improved comments for better clarity by detailing the purpose of each constant and type, and included relevant RFC links for deeper context. These changes aim to help developers quickly understand the code without needing to cross-reference external documents.
Renamed `dsn` field to `requestDSN` in Client structure for clarity and consistency. Adjusted associated methods and tests to reflect this change, improving code readability and maintainability.
Refactor variable names for consistency. The `dsnmrtype` variable has been renamed to `dsnReturnType` across the client and test files to improve code readability and maintain uniformity.
Renamed the variable from `dsnrntype` to `dsnRcptNotifyType` to improve code readability and ensure clarity regarding its purpose. Also updated corresponding comments and test cases to reflect this change.
Rephrase comments to enhance clarity and maintain consistent style. Improved explanations for fields such as `smtpAuth`, `helo`, and `noNoop`, and standardize grammar and format across all comments. This helps in better understanding the code and its functionality.
Updated error comments to provide clearer and more descriptive explanations. Enhanced readability by elaborating on the conditions that result in each error, giving developers better context. No functional changes to the code were made.
Enhanced the documentation for NewClient and related option functions to provide clearer descriptions. Added validation details for WithPort and WithTimeout, and improved explanations for SSL/TLS settings.
Revised the comments for `WithSSLPort`, `WithDebugLog`, `WithLogger`, and `WithHELO` options to improve readability and provide clearer explanations. Added caution about potential data protection issues when using debug logging and specified defaults where applicable.
Updated comments for WithTLSPolicy and WithTLSPortPolicy to provide clearer explanations. Improved readability and emphasized recommended best practices for SMTP TLS connections.
Revised comments provide clearer guidance on the usage of various client configuration functions. Additional details and external references are included for better understanding and error handling.
Correct typos and enhance clarity in method descriptions. Provide additional context for default values and behavior, and specify consequences for security settings in client configurations.
Introduce the SMTPAuthCustom type to represent user-defined SMTP authentication mechanisms. Updated relevant functions in client.go to handle the new type appropriately and made sure the client distinguishes between built-in and custom authentication methods.
Previously, only the presence of the SMTP auth method was checked, but not its type. This additional validation ensures that the SMTP auth type is correctly set to custom, thereby improving test accuracy.
Reordered several functions within client.go for better code organization and readability. This change involves moving `setDefaultHelo`, `checkConn`, `serverFallbackAddr`, and `tls` functions to new locations without altering their implementations.
Reset connections to nil after Close, add RLock in HasConnection, and refine Close logic to handle already closed connections gracefully. Enhanced DialWithContext documentation and added tests for double-close scenarios to ensure robustness.
Updated function comments across client.go to improve clarity and consistency. Added missing details on error handling and context usage for `DialAndSendWithContext` and ensured all functions contain relevant, detailed descriptions.
Simplify comments in `client.go` to improve code documentation. Ensure comments are more descriptive and provide context for the functions they describe, enhancing code readability and maintainability.
Introduced the isConnected boolean flag in the Client struct to clearly indicate whether there is an active connection. Updated relevant methods to set this flag accordingly, ensuring consistent state management across the Client's lifecycle.
This commit introduces tests for various TLS-related methods such as GetTLSConnectionState, HasConnection, SetDSNMailReturnOption, SetDSNRcptNotifyOption, and UpdateDeadline. It also modifies the error handling logic in smtp.go to include new error types and improves the mutex handling in UpdateDeadline.
Enhanced the documentation of the `Send` function to explicitly describe the behavior when the Client has no active connection and the handling of multiple message transmissions. This ensures developers understand the error handling mechanism and the association of `SendError` with each message.
Expand the package mail description to highlight ease of use, reliance on the Go Standard Library, and added functionalities. Clarify the role of VERSION in the user agent string.
Ensure all go doc comments in eml.go have consistent punctuation by adding periods to the end of each comment. This improves code readability and maintains uniformity in the documentation style.
Revised the comments to provide more detailed descriptions and context for each type and constant. Additionally, included relevant RFC document references where applicable to improve understanding of encoding and MIME types.
Improved comments for better readability and understanding. Enhanced descriptions for File, FileOption, and various methods, providing more context and precision. Added notes on default behaviors and specific use cases for methods where applicable.
Upgraded golang.org/x/crypto to v0.28.0 and golang.org/x/text to v0.19.0. These updates improve security and compatibility with recent changes in Go modules. Ensure to run `go mod tidy` to clean up any unused dependencies.
Enhanced the descriptive comments for error variables, constants, and types to provide clearer and more detailed explanations. This improves code readability and ensures that the purpose and usage of different elements are better understood by developers.
Updated comments for all fields in the Msg struct to provide clearer and more detailed explanations. This includes specifying the data type for each field and the role they play within the Msg struct, making the code easier to understand and maintain.
Revised the comments for MsgOption functions to provide clearer explanations of their purpose and usage. Added detailed descriptions for options such as WithMIMEVersion and WithBoundary to clarify their contexts and constraints.
Enhanced the comments for various methods in `msg.go`, `client.go`, `auth.go`, and `encoding.go` to provide more detailed explanations, context, and relevant RFC references. This improves the clarity and maintainability of the code by providing developers with a deeper understanding of each method's purpose and usage.
Updated comments in `header.go` and `msg.go` to provide more detailed explanations and references to RFC 5322. This improves clarity on how headers are set and utilized, and the conditions under which they operate.
Expanded the documentation for the EnvelopeFromFormat method to clarify its purpose, usage, and compliance with RFC 5322. Added details on how the envelope from address is used in SMTP communication and validation requirements.
Detailed doc comments have been added to various methods handling "From", "To", "CC", "BCC", and "Reply-To" email addresses within the Msg class. The new comments follow RFC 5322 standards and provide explicit descriptions of the functionality and validation rules for each method. This improves code readability and maintainability. Additionally, moved the `addAddr` function to a more appropriate position within the file.
Enhanced the documentation for several Msg methods to provide clearer explanations and include relevant RFC references. This includes improved descriptions of functionality, parameter details, return values, and links to pertinent RFC sections.
This commit enhances the docstrings for the MsgOption functions and related methods in msg.go, providing extensive explanations, parameters, and references. It helps users understand the functionality, usage, and context of each function, improving code readability and usability.
Enhanced method documentation by adding parameter descriptions and reference links. This improves the clarity and usability of the code, ensuring that users understand the purpose and usage of each method.
Enhanced function documentation by adding detailed descriptions of parameters and return values for various methods. This clarifies expected inputs and outputs, improving code readability and maintainability.
Added detailed comments to various methods in `msg.go` for clarity. Each method now includes a declaration, a detailed description, returned values, parameters, and relevant RFC references. This enhances code readability and maintainability.
Expanded docstrings for methods in msg.go to provide detailed explanations, parameters, and return values. This improves clarity and helps developers understand usage and behavior more effectively.
Enhanced comments and docstrings for better readability and detail in client.go and b64linebreaker.go. Updated descriptions, added parameter and return details, and included RFC references where applicable for improved documentation quality.
Enhance the SMTP client method documentation by adding detailed explanations of the methods' purposes, parameters, return values, and operational flow. This improves clarity, making it easier for developers to understand the functionality and usage of each method.
Updated the documentation for the Send method in client_119.go and client_120.go to provide clearer explanations, include detailed descriptions of parameters, and specify return values. Ensured consistency across files by elaborating on error handling and connection checks.
Added detailed doc comments to EML parsing functions, specifying parameters, return values, and providing thorough explanations of functionalities to improve code understandability and maintainability. This helps future developers and users comprehend the usage and behavior of these functions more effectively.
Enhanced comments for String methods on Charset, ContentType, and Encoding types. Detailed the purpose and usage of each method, emphasizing their role in formatted output and logging.
Updated documentation for the `File` struct and its methods, providing clearer explanations and detailed parameter and return descriptions. Improved readability and consistency of comments across the codebase.
Updated the documentation for NumString, XPrioString, and String methods in the Importance type to provide clearer descriptions of their behavior and return values. Enhanced comments for better readability and maintainability of the code.
Clarify the documentation for WriteToTempFile to better explain its functionality, ensure consistency, and detail its return values.
Streamline msgWriter by adding detailed documentation for each method and constant. This includes parameter descriptions, return values, and references to relevant RFCs, improving code readability and maintainability.
Enhanced the documentation of `Part` struct and its methods to provide clearer explanations, including parameter and return descriptions. This improves code readability and helps developers understand the functionality and usage of each method.
Expanded randNum function comments to provide detailed behavior and usage across different Go versions. Enhanced the randomStringSecure function doc to explain its cryptographic secure implementation and error handling.
Improved documentation for the Reader struct, its methods, and error handling. Added detailed explanations for `Read`, `Error`, `Reset`, and `empty` functions to better describe their parameters, return values, and behavior.
Improved comments for better clarity and detail in SendError-related methods and fields. Updated comments provide more in-depth explanations of functionality, parameters, return values, and usage.
Updated the TLSPolicy type documentation to improve clarity and consistency. Enhanced the String method with detailed commentary and return value explanation, ensuring it better adheres to the fmt.Stringer interface.
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #324 +/- ##
==========================================
+ Coverage 86.00% 86.90% +0.90%
==========================================
Files 27 27
Lines 2350 2359 +9
==========================================
+ Hits 2021 2050 +29
+ Misses 200 179 -21
- Partials 129 130 +1 ☔ View full report in Codecov by Sentry. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR revises the GoDoc documenation comments for the whole package. It provides much more details for each method in a more standardised format, allowing users of the package to get better information on what does what. This is also especially helpful for LSP implementations like gopls.