Add comments to InventoryController

src/main/java/catering/inventory/InventoryController.java

@@ -72,6 +72,12 @@ class InventoryController {
 		this.cateringCatalog = cateringCatalog;
 	}
 
+	/**
+	 * Lists all inventory products.
+	 *
+	 * @param model an instance of {@link Model}
+	 * @return the inventory template
+	 */
 	@GetMapping("/inventory")
 	String list(Model model) {
 		model.addAttribute("inventory", inventory.findAll());
@@ -79,6 +85,13 @@ class InventoryController {
 		return "inventory";
 	}
 
+	/**
+	 * Returns the edit page for an inventory product.
+	 *
+	 * @param model an instance of {@link Model}
+	 * @param pid   the {@link Product} to edit
+	 * @return the inventory-mutate template with the {@link Product} data prefilled
+	 */
 	@GetMapping("/inventory/edit/{pid}")
 	String edit(Model model, @PathVariable Product pid) {
 		UniqueInventoryItem item = inventory.findByProduct(pid).get();
@@ -87,6 +100,17 @@ class InventoryController {
 		return edit(model, form);
 	}
 
+	/**
+	 * Returns the edit page for an inventory product.
+	 *
+	 * This method is not mapped,
+	 * but is used by other methods to generalise the display of the edit page.
+	 *
+	 * @param model an instance of {@link Model}
+	 * @param form  an already filled or empty {@link InventoryMutateForm}
+	 * @return the inventory-mutate template with the {@link InventoryMutateForm}
+	 *         data prefilled
+	 */
 	String edit(Model model, InventoryMutateForm form) {
 		model.addAttribute("actionIsAdd", false);
 		model.addAttribute("form", form);
@@ -94,18 +118,54 @@ class InventoryController {
 		return "inventory-mutate";
 	}
 
+	/**
+	 * Edits a consumable.
+	 *
+	 * @param form   a user-filled {@link ConsumableMutateForm}
+	 * @param errors an {@link Errors} object including validation errors
+	 * @param pid    the {@link Product} to edit
+	 * @param model  an instance of {@link Model}
+	 * @return a redirect on success, otherwise the filled form with all errors
+	 *         highlighted
+	 */
 	@PostMapping(path = "/inventory/edit/{pid}", params = "type=Consumable")
 	String editConsumable(@Valid @ModelAttribute("form") ConsumableMutateForm form, Errors result,
 			@PathVariable Consumable pid, Model model) {
 		return edit(form, result, pid, model);
 	}
 
+	/**
+	 * Edits a rentable.
+	 *
+	 * @param form   a user-filled {@link RentableMutateForm}
+	 * @param errors an {@link Errors} object including validation errors
+	 * @param pid    the {@link Product} to edit
+	 * @param model  an instance of {@link Model}
+	 * @return a redirect on success, otherwise the filled form with all errors
+	 *         highlighted
+	 */
 	@PostMapping(path = "/inventory/edit/{pid}", params = "type=Rentable")
 	String editRentable(@Valid @ModelAttribute("form") RentableMutateForm form, Errors result,
 			@PathVariable Rentable pid, Model model) {
 		return edit(form, result, pid, model);
 	}
 
+	/**
+	 * Edits an inventory product.
+	 *
+	 * This method is not mapped,
+	 * but is used by
+	 * {@link #editConsumable(ConsumableMutateForm, Errors, Consumable, Model)}
+	 * and {@link #editRentable(RentableMutateForm, Errors, Rentable, Model)}
+	 * to generalise the editing of products.
+	 *
+	 * @param form    a user-filled {@link RentableMutateForm}
+	 * @param errors  an {@link Errors} object including validation errors
+	 * @param product the {@link Product} to edit
+	 * @param model   an instance of {@link Model}
+	 * @return a redirect on success, otherwise the filled form with all errors
+	 *         highlighted
+	 */
 	String edit(InventoryMutateForm form, Errors result, Product product, Model model) {
 		if (result.hasErrors()) {
 			return edit(model, form);
@@ -121,6 +181,14 @@ class InventoryController {
 		return "redirect:/inventory";
 	}
 
+	/**
+	 * Returns the add page for a new inventory product.
+	 *
+	 * @param model an instance of {@link org.springframework.ui.Model}
+	 * @param type  string representation of a {@link Product} subclass supported by
+	 *              {@link InventoryMutateForm}
+	 * @return the inventory-mutate template with no data prefilled
+	 */
 	@GetMapping(path = "/inventory/add")
 	String add(Model model, @RequestParam String type) {
 		switch (type) {
@@ -134,22 +202,60 @@ class InventoryController {
 		}
 	}
 
+	/**
+	 * Returns the add page for a new inventory product.
+	 *
+	 * This method is not mapped,
+	 * but is used by other methods to generalise the display of the add page.
+	 *
+	 * @param model an instance of {@link Model}
+	 * @param form  an already filled or empty {@link InventoryMutateForm}
+	 * @return the inventory-mutate template with the {@link InventoryMutateForm}
+	 *         data prefilled
+	 */
 	String add(Model model, InventoryMutateForm form) {
 		model.addAttribute("actionIsAdd", true);
 		model.addAttribute("form", form);
 		return "inventory-mutate";
 	}
 
+	/**
+	 * Adds a consumable.
+	 *
+	 * @param form   a user-filled {@link ConsumableMutateForm}
+	 * @param errors an {@link Errors} object including validation errors
+	 * @param model  an instance of {@link Model}
+	 * @return a redirect on success, otherwise the filled form with all errors
+	 *         highlighted
+	 */
 	@PostMapping(path = "/inventory/add", params = "type=Consumable")
 	String addConsumable(@Valid @ModelAttribute("form") ConsumableMutateForm form, Errors result, Model model) {
 		return add(form, result, model);
 	}
 
+	/**
+	 * Adds a rentable.
+	 *
+	 * @param form   a user-filled {@link RentableMutateForm}
+	 * @param errors an {@link Errors} object including validation errors
+	 * @param model  an instance of {@link Model}
+	 * @return a redirect on success, otherwise the filled form with all errors
+	 *         highlighted
+	 */
 	@PostMapping(path = "/inventory/add", params = "type=Rentable")
 	String addRentable(@Valid @ModelAttribute("form") RentableMutateForm form, Errors result, Model model) {
 		return add(form, result, model);
 	}
 
+	/**
+	 * Adds an inventory product.
+	 *
+	 * @param form   a user-filled {@link InventoryMutateForm}
+	 * @param errors an {@link Errors} object including validation errors
+	 * @param model  an instance of {@link Model}
+	 * @return a redirect on success, otherwise the filled form with all errors
+	 *         highlighted
+	 */
 	String add(@Valid InventoryMutateForm form, Errors result, Model model) {
 		if (result.hasErrors()) {
 			return add(model, form);
@@ -158,6 +264,12 @@ class InventoryController {
 		return "redirect:/inventory";
 	}
 
+	/**
+	 * Deletes an inventory product.
+	 *
+	 * @param pid the {@link Product} to delete
+	 * @return a redirect to the inventory overview
+	 */
 	@GetMapping("/inventory/delete/{pid}")
 	String delete(@PathVariable Product pid) {
 		UniqueInventoryItem item = inventory.findByProduct(pid).get();