Add Comprehensive Docstrings to Codebase issue solution#51
Open
CBHeithoff wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR addresses Issue #28 by adding/expanding Javadoc across the BankingPortal API codebase to document responsibilities, request/response contracts, and exception behavior for entities, DTOs, services, controllers, repositories, configuration, and utilities.
Changes:
- Added class/method/field Javadoc across core layers (controllers/services/entities/repositories).
- Added contract-style Javadoc to service interfaces and request/response DTOs.
- Added descriptive documentation to config/types/utilities to explain runtime behavior (security, caching, Redis, etc.).
Reviewed changes
Copilot reviewed 76 out of 76 changed files in this pull request and generated 16 comments.
Show a summary per file
| File | Description |
|---|---|
| src/main/java/com/webapp/bankingportal/util/ValidationUtil.java | Added Javadoc for validation helpers and uniqueness checks. |
| src/main/java/com/webapp/bankingportal/util/ApiMessages.java | Documented enum purpose/usage for centralized messages. |
| src/main/java/com/webapp/bankingportal/type/CacheValueType.java | Documented cache value serialization expectations. |
| src/main/java/com/webapp/bankingportal/type/CacheKeyType.java | Documented cache key patterns, TTL, and key generation. |
| src/main/java/com/webapp/bankingportal/service/UserServiceImpl.java | Added implementation-level Javadoc for user flows/helpers. |
| src/main/java/com/webapp/bankingportal/service/UserService.java | Added contract Javadoc for user operations and exceptions. |
| src/main/java/com/webapp/bankingportal/service/TransactionServiceImpl.java | Added class-level Javadoc for transaction/statement responsibilities. |
| src/main/java/com/webapp/bankingportal/service/TransactionService.java | Added contract Javadoc for transaction retrieval and statement delivery. |
| src/main/java/com/webapp/bankingportal/service/TokenServiceImpl.java | Added class/method Javadoc around JWT lifecycle implementation. |
| src/main/java/com/webapp/bankingportal/service/TokenService.java | Added contract Javadoc for token lifecycle and UserDetailsService role. |
| src/main/java/com/webapp/bankingportal/service/OtpServiceImpl.java | Added class/method Javadoc for OTP rate-limit and lifecycle logic. |
| src/main/java/com/webapp/bankingportal/service/OtpService.java | Added contract Javadoc for OTP generation/sending/validation. |
| src/main/java/com/webapp/bankingportal/service/GeolocationServiceImpl.java | Added class/field Javadoc for async external geo API usage. |
| src/main/java/com/webapp/bankingportal/service/GeolocationService.java | Added contract Javadoc for async geolocation resolution. |
| src/main/java/com/webapp/bankingportal/service/EmailServiceImpl.java | Added class/method Javadoc describing async email sending and attachment behavior. |
| src/main/java/com/webapp/bankingportal/service/EmailService.java | Added contract Javadoc for composing and sending HTML emails. |
| src/main/java/com/webapp/bankingportal/service/DashboardServiceImpl.java | Added class-level Javadoc for dashboard DTO projections. |
| src/main/java/com/webapp/bankingportal/service/DashboardService.java | Added contract Javadoc for dashboard user/account summaries. |
| src/main/java/com/webapp/bankingportal/service/CacheServiceImpl.java | Added class/method Javadoc for Redis-backed cache operations. |
| src/main/java/com/webapp/bankingportal/service/CacheService.java | Added contract Javadoc for cache access patterns and typing. |
| src/main/java/com/webapp/bankingportal/service/AuthServiceImpl.java | Added class/method Javadoc for password-reset orchestration. |
| src/main/java/com/webapp/bankingportal/service/AuthService.java | Added contract Javadoc documenting password-reset flow steps. |
| src/main/java/com/webapp/bankingportal/service/AccountServiceImpl.java | Added Javadoc for account operations, PIN/password checks, amount validation. |
| src/main/java/com/webapp/bankingportal/service/AccountService.java | Added contract Javadoc for account management and transaction operations. |
| src/main/java/com/webapp/bankingportal/repository/UserRepository.java | Added repository/interface method Javadoc. |
| src/main/java/com/webapp/bankingportal/repository/TransactionRepository.java | Added Javadoc for transaction query method. |
| src/main/java/com/webapp/bankingportal/repository/TokenRepository.java | Added Javadoc for token repository methods. |
| src/main/java/com/webapp/bankingportal/repository/PasswordResetTokenRepository.java | Added Javadoc for reset-token repository methods. |
| src/main/java/com/webapp/bankingportal/repository/OtpInfoRepository.java | Added Javadoc for OTP repository methods. |
| src/main/java/com/webapp/bankingportal/repository/AccountRepository.java | Added Javadoc for account lookup method. |
| src/main/java/com/webapp/bankingportal/mapper/UserMapper.java | Added mapper contract Javadoc for update semantics. |
| src/main/java/com/webapp/bankingportal/mapper/TransactionMapper.java | Added mapper method Javadoc for entity→DTO conversion. |
| src/main/java/com/webapp/bankingportal/exception/UserInvalidException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/UnauthorizedException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/PasswordResetException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/OtpRetryLimitExceededException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/NotFoundException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/InvalidTokenException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/InvalidPinException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/InvalidOtpException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/InvalidAmountException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/InsufficientBalanceException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/GeolocationException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/FundTransferException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/exception/AccountDoesNotExistException.java | Added exception Javadoc and constructor documentation. |
| src/main/java/com/webapp/bankingportal/entity/User.java | Added class/field documentation for user entity and relationships. |
| src/main/java/com/webapp/bankingportal/entity/TransactionType.java | Added enum documentation for transaction categories. |
| src/main/java/com/webapp/bankingportal/entity/Transaction.java | Added class/field documentation for transaction entity semantics. |
| src/main/java/com/webapp/bankingportal/entity/Token.java | Added class/field/constructor documentation for persisted JWT tokens. |
| src/main/java/com/webapp/bankingportal/entity/PasswordResetToken.java | Added class/field/method documentation for reset tokens. |
| src/main/java/com/webapp/bankingportal/entity/OtpInfo.java | Added class/field/constructor documentation for OTP persistence. |
| src/main/java/com/webapp/bankingportal/entity/Account.java | Added class/field documentation for account entity and relations. |
| src/main/java/com/webapp/bankingportal/dto/UserResponse.java | Added DTO documentation and projection-constructor docs. |
| src/main/java/com/webapp/bankingportal/dto/TransactionDTO.java | Added DTO documentation and entity-projection constructor docs. |
| src/main/java/com/webapp/bankingportal/dto/ResetPasswordRequest.java | Added request-record Javadoc with @param tags. |
| src/main/java/com/webapp/bankingportal/dto/PinUpdateRequest.java | Added request-record Javadoc with @param tags. |
| src/main/java/com/webapp/bankingportal/dto/PinRequest.java | Added request-record Javadoc with @param tags. |
| src/main/java/com/webapp/bankingportal/dto/OtpVerificationRequest.java | Added request-record Javadoc with @param tags. |
| src/main/java/com/webapp/bankingportal/dto/OtpRequest.java | Added request-record Javadoc with @param tags. |
| src/main/java/com/webapp/bankingportal/dto/LoginRequest.java | Added request-record Javadoc with @param tags. |
| src/main/java/com/webapp/bankingportal/dto/GeolocationResponse.java | Added DTO documentation mapping external geo API payload. |
| src/main/java/com/webapp/bankingportal/dto/FundTransferRequest.java | Added request-record Javadoc with @param tags. |
| src/main/java/com/webapp/bankingportal/dto/ErrorResponse.java | Added error-body record documentation. |
| src/main/java/com/webapp/bankingportal/dto/AmountRequest.java | Added request-record Javadoc with @param tags. |
| src/main/java/com/webapp/bankingportal/dto/AccountResponse.java | Added DTO documentation and projection-constructor docs. |
| src/main/java/com/webapp/bankingportal/controller/UserController.java | Added controller/endpoint Javadoc for user flows. |
| src/main/java/com/webapp/bankingportal/controller/GlobalExceptionHandler.java | Added centralized exception-handler documentation. |
| src/main/java/com/webapp/bankingportal/controller/DashboardController.java | Added endpoint documentation for dashboard read APIs. |
| src/main/java/com/webapp/bankingportal/controller/AuthController.java | Added endpoint documentation for password-reset flow. |
| src/main/java/com/webapp/bankingportal/controller/AccountController.java | Added controller/endpoint documentation for account operations and idempotency. |
| src/main/java/com/webapp/bankingportal/config/WebSecurityConfig.java | Added documentation for JWT-based security configuration. |
| src/main/java/com/webapp/bankingportal/config/SwaggerConfig.java | Added documentation for OpenAPI/Swagger configuration. |
| src/main/java/com/webapp/bankingportal/config/RedisConfig.java | Added documentation for RedisTemplate serialization config. |
| src/main/java/com/webapp/bankingportal/config/CorsConfig.java | Added documentation for permissive global CORS setup. |
| src/main/java/com/webapp/bankingportal/config/CacheConfig.java | Added documentation for Caffeine cache setup and OTP attempts cache. |
| src/main/java/com/webapp/bankingportal/BankingportalApplication.java | Added application entry-point documentation and cleaned inline comment. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @GeneratedValue(strategy = GenerationType.IDENTITY) | ||
| private Long id; | ||
|
|
||
| /** Unique 6-digit account number assigned on account creation. */ |
| /** Residential address of the user. */ | ||
| private String address; | ||
|
|
||
| /** The unique 6-digit account number linked to this user. */ |
| @AllArgsConstructor | ||
| public class AccountResponse { | ||
|
|
||
| /** The unique 6-digit account number. */ |
| /** | ||
| * Request body for standard password-based login. | ||
| * | ||
| * @param identifier either the user's email address or 6-digit account number |
| /** | ||
| * Request body for generating and sending an OTP to a user. | ||
| * | ||
| * @param identifier either the user's email address or 6-digit account number |
Comment on lines
+3
to
12
| /** | ||
| * Request body for updating an existing transaction PIN on an account. | ||
| * | ||
| * @param accountNumber the account number whose PIN is being updated | ||
| * @param oldPin the current 4-digit PIN to verify ownership | ||
| * @param newPin the new 4-digit numeric PIN to set | ||
| * @param password the account holder's login password for additional identity verification | ||
| */ | ||
| public record PinUpdateRequest(String accountNumber, String oldPin, String newPin, String password) { | ||
| } |
Comment on lines
+6
to
+9
| * @param sourceAccountNumber the account number from which funds are debited | ||
| * @param targetAccountNumber the account number to which funds are credited | ||
| * @param amount the monetary amount to transfer (must be a positive multiple of 100, max 100,000) | ||
| * @param pin the 4-digit PIN of the source account authorizing the transfer |
Comment on lines
+28
to
+30
| * <p>State-changing endpoints (deposit, withdraw, fund-transfer, PIN create/update) | ||
| * are guarded by an idempotency cache so that duplicate requests within the TTL window | ||
| * are safely deduplicated.</p> |
Comment on lines
+21
to
+28
| /** | ||
| * Sends a plain-text bank statement for the given account to the account | ||
| * holder's registered email address. | ||
| * | ||
| * @param accountNumber the account number whose statement is to be emailed | ||
| * @throws IllegalArgumentException if {@code accountNumber} is null or blank | ||
| */ | ||
| void sendBankStatementByEmail(String accountNumber); |
Comment on lines
+23
to
+26
| * <p>Tokens are issued after OTP verification and are valid for | ||
| * {@code AuthServiceImpl#EXPIRATION_HOURS} hours. Once used they are deleted. | ||
| * Implements {@link Serializable} to support sequence-generator strategies | ||
| * across JPA providers.</p> |
This file contains hidden or 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
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.
Solution for Git Issue Add Comprehensive Docstrings to Codebase #28
Comprehensive Javadoc has been added to all 75+ Java files in the codebase. The build compiles. Here's a summary of what was documented:
Entities (Account, User, Transaction, Token, OtpInfo, PasswordResetToken, TransactionType): class-level summaries, field-level inline docs, constructor docs
DTOs (all 10 records/classes): class-level summaries with @param tags on record components, constructor docs
Service interfaces (all 10): detailed method contracts with @param, @return, and @throws documenting all exception types
Service implementations (all 10): class-level summaries explaining responsibilities; all private helper methods documented
Controllers (all 5 including GlobalExceptionHandler): class-level summaries; every endpoint and handler method documented with HTTP response codes
Repositories (all 6): interface summaries; custom query methods documented
Exception classes (all 13): class descriptions with the HTTP status code each maps to; constructor docs
Config, Security, Mappers, Utils, Types, Main: class summaries; all @bean methods, public methods, and enum constants documented