Improve Javadoc Comments for Better Clarity and Accessibility

src/main/java/com/libraryman_api/book/BookController.java

@@ -9,46 +9,73 @@
 
 /**
  * REST controller for managing books in the LibraryMan application.
- * This controller provides endpoints for performing CRUD operations on books,
- * including retrieving all books, getting a book by its ID, adding a new book,
- * updating an existing book, and deleting a book.
+ *
+ * <p>This controller provides a set of endpoints for performing CRUD operations 
+ * on books. The operations include retrieving a list of all books, fetching 
+ * a book by its ID, adding a new book, updating an existing book, and deleting 
+ * a book.</p>
+ *
+ * <p>All endpoints are accessible under the base URL path <code>/api/books</code>.</p>
+ * 
+ * <p>Note: The {@link ResourceNotFoundException} is thrown when an invalid book ID is 
+ * provided for retrieval, update, or deletion.</p>
+ * 
+ * <p>Usage examples for each endpoint can be found in the API documentation.</p>
  */
 @RestController
 @RequestMapping("/api/books")
 public class BookController {
 
+    private final BookService bookService;
+
+    /**
+     * Constructs a new {@code BookController} with the specified {@code BookService}.
+     *
+     * @param bookService the service used to manage book operations
+     */
     @Autowired
-    private BookService bookService;
+    public BookController(BookService bookService) {
+        this.bookService = bookService;
+    }
 
     /**
      * Retrieves a list of all books in the library.
      *
-     * @return a list of {@link Book} objects representing all the books in the library.
+     * <p>This endpoint handles GET requests to <code>/api/books</code> and 
+     * returns a list of all books currently available in the library.</p>
+     *
+     * @return a list of {@link Book} objects representing all books in the library
      */
     @GetMapping
     public List<Book> getAllBooks() {
         return bookService.getAllBooks();
     }
 
     /**
-     * Retrieves a book by its ID.
+     * Retrieves a specific book by its ID.
+     *
+     * <p>This endpoint handles GET requests to <code>/api/books/{id}</code> 
+     * and returns the details of the book with the specified ID.</p>
      *
-     * @param id the ID of the book to retrieve.
-     * @return a {@link ResponseEntity} containing the {@link Book} object, if found.
-     * @throws ResourceNotFoundException if the book with the specified ID is not found.
+     * @param id the ID of the book to retrieve
+     * @return a {@link ResponseEntity} containing the {@link Book} object if found
+     * @throws ResourceNotFoundException if the book with the specified ID is not found
      */
     @GetMapping("/{id}")
     public ResponseEntity<Book> getBookById(@PathVariable int id) {
         return bookService.getBookById(id)
                 .map(ResponseEntity::ok)
-                .orElseThrow(() -> new ResourceNotFoundException("Book not found"));
+                .orElseThrow(() -> new ResourceNotFoundException("Book with ID " + id + " not found"));
     }
 
     /**
      * Adds a new book to the library.
      *
-     * @param book the {@link Book} object representing the new book to add.
-     * @return the added {@link Book} object.
+     * <p>This endpoint handles POST requests to <code>/api/books</code> 
+     * to add a new book to the library.</p>
+     *
+     * @param book the {@link Book} object representing the new book to add
+     * @return the added {@link Book} object
      */
     @PostMapping
     public Book addBook(@RequestBody Book book) {
@@ -58,9 +85,13 @@ public Book addBook(@RequestBody Book book) {
     /**
      * Updates an existing book in the library.
      *
-     * @param id          the ID of the book to update.
-     * @param bookDetails the {@link Book} object containing the updated book details.
-     * @return the updated {@link Book} object.
+     * <p>This endpoint handles PUT requests to <code>/api/books/{id}</code> 
+     * to update the details of an existing book in the library.</p>
+     *
+     * @param id the ID of the book to update
+     * @param bookDetails the updated {@link Book} details
+     * @return the updated {@link Book} object
+     * @throws ResourceNotFoundException if the book with the specified ID is not found
      */
     @PutMapping("/{id}")
     public Book updateBook(@PathVariable int id, @RequestBody Book bookDetails) {
@@ -70,7 +101,11 @@ public Book updateBook(@PathVariable int id, @RequestBody Book bookDetails) {
     /**
      * Deletes a book from the library by its ID.
      *
-     * @param id the ID of the book to delete.
+     * <p>This endpoint handles DELETE requests to <code>/api/books/{id}</code> 
+     * to remove a book from the library.</p>
+     *
+     * @param id the ID of the book to delete
+     * @throws ResourceNotFoundException if the book with the specified ID is not found
      */
     @DeleteMapping("/{id}")
     public void deleteBook(@PathVariable int id) {

src/main/java/com/libraryman_api/book/BookService.java

@@ -7,94 +7,115 @@
 import java.util.Optional;
 
 /**
- * Service class for managing books in the LibraryMan system.
+ * Service class responsible for managing book-related operations in the LibraryMan system.
  *
- * <p>This service provides methods to perform CRUD operations on books, including
- * retrieving all books, retrieving a book by its ID, adding a new book, updating
- * an existing book, and deleting a book by its ID.</p>
+ * <p>This service handles various CRUD operations, such as retrieving all books, fetching 
+ * a book by its ID, adding a new book, updating book details, and deleting a book from the system.</p>
  *
- * <p>Each method in this service interacts with the {@link BookRepository} to
- * perform database operations.</p>
- *
- * <p>In the case of an invalid book ID being provided, the service throws a
+ * <p>All interactions with the database are facilitated via the {@link BookRepository}. 
+ * If a book with a given ID is not found, the service throws a 
  * {@link ResourceNotFoundException}.</p>
- *
- * @author Ajay Negi
+ * 
+ * <p>Usage examples and further documentation on the book management process 
+ * can be found in the associated API documentation.</p>
+ * 
+ * @see BookRepository
+ * @see ResourceNotFoundException
+ * @author
  */
 @Service
 public class BookService {
 
     private final BookRepository bookRepository;
 
     /**
-     * Constructs a new {@code BookService} with the specified {@code BookRepository}.
+     * Constructs a new {@code BookService} instance, injecting the required 
+     * {@link BookRepository} to facilitate database operations.
      *
-     * @param bookRepository the repository to be used by this service to interact with the database
+     * @param bookRepository the repository used to access and modify book data in the database
      */
     public BookService(BookRepository bookRepository) {
         this.bookRepository = bookRepository;
     }
 
     /**
-     * Retrieves all books from the database.
+     * Retrieves all books stored in the library.
+     *
+     * <p>This method interacts with the database to fetch a complete list of 
+     * all {@link Book} entities available in the library's collection.</p>
      *
-     * @return a list of all books
+     * @return a {@link List} of all books in the system
      */
     public List<Book> getAllBooks() {
         return bookRepository.findAll();
     }
 
     /**
-     * Retrieves a book by its ID.
+     * Fetches a specific book by its ID.
      *
-     * @param bookId the ID of the book to retrieve
-     * @return an {@code Optional} containing the found book, or {@code Optional.empty()} if no book was found
+     * <p>If the book with the specified ID exists, it is returned as an 
+     * {@link Optional}. If the book is not found, {@code Optional.empty()} is returned.</p>
+     *
+     * @param bookId the unique identifier of the book to be retrieved
+     * @return an {@link Optional} containing the book if found, or {@code Optional.empty()} if not
      */
     public Optional<Book> getBookById(int bookId) {
         return bookRepository.findById(bookId);
     }
 
     /**
-     * Adds a new book to the database.
+     * Adds a new book to the library.
+     *
+     * <p>This method saves the provided {@link Book} entity to the database. 
+     * The book entity must contain the necessary details such as title, author, 
+     * and publication details.</p>
      *
-     * @param book the book to be added
-     * @return the saved book
+     * @param book the {@link Book} object to be added to the library
+     * @return the saved {@link Book} entity with any auto-generated fields populated (e.g., ID)
      */
     public Book addBook(Book book) {
         return bookRepository.save(book);
     }
 
     /**
-     * Updates an existing book with the given details.
+     * Updates an existing book's details.
      *
-     * @param bookId the ID of the book to update
-     * @param bookDetails the new details for the book
-     * @return the updated book
-     * @throws ResourceNotFoundException if the book with the specified ID is not found
+     * <p>When called, this method updates the properties of an existing book 
+     * using the new data passed in {@code bookDetails}. If the book with the 
+     * specified ID does not exist, a {@link ResourceNotFoundException} is thrown.</p>
+     *
+     * @param bookId the unique identifier of the book to update
+     * @param bookDetails the new details to be applied to the book
+     * @return the updated {@link Book} object after saving the changes
+     * @throws ResourceNotFoundException if the book with the specified ID does not exist
      */
     public Book updateBook(int bookId, Book bookDetails) {
         Book book = bookRepository.findById(bookId)
-                .orElseThrow(() -> new ResourceNotFoundException("Book not found"));
+                .orElseThrow(() -> new ResourceNotFoundException("Book with ID " + bookId + " not found"));
+
         book.setTitle(bookDetails.getTitle());
         book.setAuthor(bookDetails.getAuthor());
         book.setIsbn(bookDetails.getIsbn());
         book.setPublisher(bookDetails.getPublisher());
         book.setPublishedYear(bookDetails.getPublishedYear());
         book.setGenre(bookDetails.getGenre());
         book.setCopiesAvailable(bookDetails.getCopiesAvailable());
+
         return bookRepository.save(book);
     }
 
     /**
-     * Deletes a book by its ID.
+     * Deletes a book from the library by its ID.
      *
-     * @param bookId the ID of the book to delete
+     * <p>If the book with the specified ID exists, it is removed from the system. 
+     * If not, a {@link ResourceNotFoundException} is thrown.</p>
+     *
+     * @param bookId the unique identifier of the book to delete
      * @throws ResourceNotFoundException if the book with the specified ID is not found
      */
     public void deleteBook(int bookId) {
         Book book = bookRepository.findById(bookId)
-                .orElseThrow(() -> new ResourceNotFoundException("Book not found"));
+                .orElseThrow(() -> new ResourceNotFoundException("Book with ID " + bookId + " not found"));
         bookRepository.delete(book);
     }
-
 }

src/main/java/com/libraryman_api/email/EmailSender.java

@@ -3,20 +3,41 @@
 import com.libraryman_api.notification.Notifications;
 
 /**
- * Interface representing an email sending service for the Library Management System.
- * Classes implementing this interface are responsible for sending emails
- * and updating the status of notifications in the system.
+ * Interface representing an email sending service for the LibraryMan system.
+ * 
+ * <p>This interface defines the contract for sending emails asynchronously to recipients.
+ * Implementing classes are responsible for constructing and sending the email, as well as 
+ * updating the status of notifications (represented by {@link Notifications}) within the system.</p>
+ *
+ * <p>The email sending process involves constructing an email with a subject, body, and recipient 
+ * details, and ensuring that the notification entity is updated based on whether the email 
+ * was successfully sent or encountered an error.</p>
+ *
+ * <p>Classes implementing this interface typically use a mailing service such as 
+ * {@link org.springframework.mail.javamail.JavaMailSender} to perform the actual email delivery.</p>
+ *
+ * @see Notifications
  */
 public interface EmailSender {
 
     /**
-     * Sends an email to the specified recipient with the given body, subject, and notification details.
-     *
+     * Sends an email asynchronously to the specified recipient with the provided content and subject.
+     * 
+     * <p>This method is responsible for constructing the email message, sending it to the recipient,
+     * and updating the corresponding notification status within the system based on the outcome.
+     * The email body can be in HTML or plain text format, and the associated {@link Notifications} entity
+     * tracks the status of the email (e.g., SENT or FAILED).</p>
+     * 
+     * <p>In case of errors during the sending process, the implementation of this method should handle 
+     * the exceptions and log any failures accordingly. The notification status should be updated to reflect 
+     * the success or failure of the email operation.</p>
+     * 
      * @param to           the email address of the recipient
-     * @param body         the body of the email, typically in HTML or plain text format
-     * @param subject      the subject of the email
-     * @param notification the notification entity associated with the email being sent,
-     *                     used to track the status of the notification
+     * @param body         the content of the email, either in HTML or plain text format
+     * @param subject      the subject line of the email
+     * @param notification the notification entity representing the email notification in the system, 
+     *                     used to track the status (SENT or FAILED) of the email being sent
+     * @throws IllegalStateException if there is an issue sending the email
      */
     void send(String to, String body, String subject, Notifications notification);
 }