add and improve javadoc

4 files changed, 119 insertions, 40 deletions

diff --git a/src/com.example.portfolio2/com/example/portfolio2/Controller.java b/src/com.example.portfolio2/com/example/portfolio2/Controller.java
index 031b6cc..f38a3ca 100644
--- a/src/com.example.portfolio2/com/example/portfolio2/Controller.java
+++ b/src/com.example.portfolio2/com/example/portfolio2/Controller.java
@@ -11,41 +11,66 @@ import javafx.scene.control.TextArea;
 
 import java.util.List;
 
+/// Bachelorizer - Controller
 class Controller{
+
+	/// Application model
 	private Model model;
 
-	// We do this without using the view directly like this, instead passing options.
+	/// Application view
 	private HelloApplication view;
 
-	// calls on the database
+	/// clear the participation database at program launch
 	void initialize() {
 		model.initialize();
 	}
 
+	/// default constructor
+	///
+	/// @param model  Application model
+	/// @param view   Application view
 	Controller(Model model, HelloApplication view){
 		this.model=model; this.view=view;
 	}
 
+	/// callback when category box is selected
+	///
+	/// @param combo   involved activity box
+	/// @param select  selected item
+	/// @param area    whole text area
 	void onComboSelected(ComboBox<String> combo, ComboBox<String> select, TextArea area) {
 
-		// Clear the activity selection box
+		// clear the activity selection box
 		select.getItems().clear();
-		area.clear(); // Clear text area
 
-		// Fill activity box using model method
+		// clear text area
+		area.clear();
+
+		// fill activity box using model method
 		select.getItems().addAll(model.selectProgram(combo.getValue()));
 	}
 
+	/// callback when activity box is selected
+	///
+	/// @param combo   involved activity box
+	/// @param select  selected item
+	/// @param area    whole text area
 	void onActivitySelected(ComboBox<String> combo, ComboBox<String> select, TextArea area) {
 
-		// Passes the value chosen in the box
+		// pass the value chosen in the box
 		addActivity(select.getValue(), area);
 
-		// Updates the text area based on the category choice
+		// update text area based on category choice
+		//
 		// users can choose from the ComboBox, string (activity) and the area would update.
 		updateArea(combo, area);
 	}
 
+	/// callback when subject module box is selected
+	///
+	/// @param subject1        involved 1st column subject module box
+	/// @param subject2        involved 2nd column subject module box
+	/// @param subjectModules  list of selected subject modules
 	void onSubjectModuleSelected(ComboBox<String> subject1, ComboBox<String> subject2, List<String> subjectModules) {
 
 		// Beautiful loop we've created to remove option chosen in one subject module box from the other
@@ -58,12 +83,20 @@ class Controller{
 		}
 	}
 
-	// Calls on model method to add participation in the database
+	/// add participation to database
+	/// @param s         activity identifier
+	/// @param textArea  whole text area
 	void addActivity(String s, TextArea textArea) {
 		model.addParticipation(model.getActivityIndeks(s));
 	}
 
-	// Clears the text area and adds all activity names from activities in participation
+	/// update text area for an activity box
+	///
+	/// Clears the text area
+	/// and adds all activity names from activities in participation.
+	///
+	/// @param combo     involved activity box
+	/// @param textArea  whole text area
 	void updateArea(ComboBox<String> combo, TextArea textArea) {
 		textArea.clear();
 		for(String s : model.getParticipation(combo.getValue())) {
@@ -71,7 +104,9 @@ class Controller{
 		}
 	}
 
-	// Updates the labels with the current ECTS of the program type
+	/// update label with current ECTS of program type
+	/// @param ectslabel  text display area for ECTS points
+	/// @param comboBox   involved activity box
 	void updateEcts(Label ectslabel, ComboBox<String> comboBox) {
 		ectslabel.setText("ECTS: "+model.getSumEcts(comboBox.getValue()));
 	}
diff --git a/src/com.example.portfolio2/com/example/portfolio2/HelloApplication.java b/src/com.example.portfolio2/com/example/portfolio2/HelloApplication.java
index 1fa5a62..3b754d4 100644
--- a/src/com.example.portfolio2/com/example/portfolio2/HelloApplication.java
+++ b/src/com.example.portfolio2/com/example/portfolio2/HelloApplication.java
@@ -17,13 +17,20 @@ import javafx.stage.Stage;
 import java.io.IOException;
 import java.util.List;
 
+/// Bachelorizer - bachelor programme registrar
 public class HelloApplication extends Application {
 
-	// Initializing model, controller and database objects
+	/// Default constructor
+	// (declared explicitly only to silence javadoc)
+	public HelloApplication(){}
+
+	/// Application model
 	private Model model = new Model();
 
+	/// Application controller
 	private Controller con = new Controller(model,this);
 
+	/// database singleton
 	MyDB myDB = new MyDB();
 
 	/* Below is the original implementation of the UI elements with
@@ -59,10 +66,10 @@ public class HelloApplication extends Application {
 
 	@Override
 	public void start(Stage stage) throws IOException {
-		// Clears old insertions into the participation table
+		// clear old insertions into participation table
 		con.initialize();
 
-		// Defines a list of columns based on their names.
+		// define list of columns based on their names
 		List<ActivityColumn> columns = List.of(
 			new ActivityColumn("Program"),
 			new ActivityColumn("Subject 1"),
@@ -70,10 +77,10 @@ public class HelloApplication extends Application {
 			new ActivityColumn("Elective")
 		);
 
-		// Defines a list of subject modules
+		// define list of subject modules
 		List<String> subjectModules = List.of("Computer Science", "Informatik", "Astrology");
 
-		// Loop for defining button funtionality for each activity column
+		// define button functionality for each activity column
 		for (ActivityColumn col : columns) {
 			col.nameLabel.setStyle("-fx-font-size: 18px; -fx-padding: 10px;"); // Styling
 			col.ectsLabel.setStyle("-fx-font-size: 18px; -fx-padding: 10px");
@@ -81,13 +88,13 @@ public class HelloApplication extends Application {
 			col.activitySelect.setPrefSize(250, 35);
 			col.area.setPrefWidth(250);
 
-			// All boxes share the same activity logic
+			// all boxes share same activity logic
 			col.activitySelect.setOnAction(event -> {
 				con.onActivitySelected(col.categoryCombo, col.activitySelect, col.area);
 				con.updateEcts(col.ectsLabel, col.categoryCombo);
 			});
 
-			// Switch statement handles different category boxes
+			// handle each category box
 			switch (col.name) {
 			  case "Program" -> {
 				col.categoryCombo.getItems().addAll("HumTek", "NatBach");
@@ -95,7 +102,7 @@ public class HelloApplication extends Application {
 					con.onComboSelected(col.categoryCombo, col.activitySelect, col.area);
 				});
 			}
-			  // We considered using the list for filling the box but couldn't figure it out
+			  // TODO: use the list for filling the box
 			  case "Subject 1" -> {
 				col.categoryCombo.getItems().addAll("Computer Science", "Informatik", "Astrology");
 				col.categoryCombo.setOnAction(event -> {
@@ -105,8 +112,7 @@ public class HelloApplication extends Application {
 			}
 			  case "Subject 2" -> {
 				col.categoryCombo.getItems().addAll("Computer Science", "Informatik", "Astrology");
-				// We figured we have to specify
-				// the second column like this but reckon there's a better way.
+				// TODO: figure out a better way...
 				col.categoryCombo.setOnAction(event -> {
 					con.onSubjectModuleSelected(col.categoryCombo, columns.get(1).categoryCombo, subjectModules);
 					con.onComboSelected(col.categoryCombo, col.activitySelect, col.area);
@@ -114,14 +120,15 @@ public class HelloApplication extends Application {
 			}
 			  case "Elective" -> {
 
-				// Hide useless box
+				// hide useless box
 				col.categoryCombo.setVisible(false);
+
 				con.fillElective(col.activitySelect);
 			}
 			}
 		}
 
-		// Define an HBox based on the columns and define the scene based on it.
+		// define HBox and scene for columns
 		HBox root = new HBox(columns.get(0).asVBox(), columns.get(1).asVBox(), columns.get(2).asVBox(), columns.get(3).asVBox());
 		Scene scene = new Scene(root, 1000, 500);
 		stage.setTitle("Course Selector RUC: Ultimate Deluxe Edition");
@@ -129,21 +136,37 @@ public class HelloApplication extends Application {
 		stage.show();
 	}
 
+	/// JVM entry point
+	///
+	/// @param args  command-line arguments
 	public static void main(String[] args) {
 		launch();
 	}
 
-	// Class for each column of activities
+	/// column of activities
 	private class ActivityColumn {
 
-		// Each column contains these elements
+		/// identifier stored in the text felt
 		String name;
+
+		/// display text
 		Label nameLabel;
+
+		/// dropdown list for categories
 		ComboBox<String> categoryCombo;
+
+		/// dropdown list for activities
 		ComboBox<String> activitySelect;
+
+		/// descriptionof chosen activities
 		TextArea area;
+
+		/// text to display ECTS points
 		Label ectsLabel;
 
+		/// column of activities
+		///
+		/// @param name  identifier
 		ActivityColumn(String name) {
 			this.name = name;
 			nameLabel = new Label(name);
@@ -151,15 +174,11 @@ public class HelloApplication extends Application {
 			activitySelect = new ComboBox<>();
 			area = new TextArea();
 			ectsLabel = new Label();
-			// new column, "this.name" to define and saved in the text felt,
-			// new "nameLabel" to show visual text.
-			// CategoryCombo creat a dropdown list
-			// activitySelect creat one more dropdown list with Combobox, possible to choose activity.
-			// area = new TextArea helps create a text felt to describe the chosen activity
-			// ectsLabel = new Label shows text for ects points
-
 		}
 
+		/// activity columne as VBox
+		///
+		/// @return  column of activities as VBox
 		VBox asVBox() {
 			return new VBox(nameLabel, categoryCombo, activitySelect, area, ectsLabel);
 		}
diff --git a/src/com.example.portfolio2/com/example/portfolio2/Model.java b/src/com.example.portfolio2/com/example/portfolio2/Model.java
index bafa3fc..8216ccc 100644
--- a/src/com.example.portfolio2/com/example/portfolio2/Model.java
+++ b/src/com.example.portfolio2/com/example/portfolio2/Model.java
@@ -7,18 +7,27 @@ package com.example.portfolio2;
 
 import java.util.ArrayList;
 
-// The model handles all interactions with the database
+/// Bachelorizer - database model
+///
+/// This model handles all interaction with the database.
 class Model{
-	MyDB db=new MyDB();
 
+	/// database singleton
+	MyDB db = new MyDB();
+
+	/// default constructor
+	// (declared explicitly only to silence javadoc)
 	Model(){}
 
-	// When running the program, it clears the participation database
+	/// clear the participation database at program launch
 	void initialize() {
 		clearParticipation();
 	}
 
-	// Returns the integer value of the activity's index
+	/// resolve activity index from name
+	///
+	/// @param name  activity name
+	/// @return      index of activity as integer
 	int getActivityIndeks(String name) {
 		if(name ==null) return -1;
 		ArrayList<String> result = db.query("select indeks from activity a where name is '"+name+"';", "indeks");
@@ -26,33 +35,48 @@ class Model{
 
 	}
 
-	// Inserts the given activity into participation using the activity's index
+	/// insert activity into participation
+	///
+	/// @param activityIndex  index of activity
 	void addParticipation(int activityIndex) {
 		db.cmd("insert into participation values(123, "+activityIndex+");");
 	}
 
-	// Returns all activity names from activities currently in participation
+	/// list currently participating activities
+	///
+	/// @param program  programme name
+	/// @return         names of participating activities
 	ArrayList<String> getParticipation(String program) {
 		return db.query("select name from participation p inner join activity a on p.indeks = a.indeks where program is '" + program + "';", "name");
 	}
 
-	// Removes all entries in the participation database
+	/// purge participation database
 	void clearParticipation() {
 		db.cmd("delete from participation");
 	}
 
-	// Returns an arraylist of activities within the given program
+	/// list activities within a program
+	///
+	/// @param program  programme name
+	/// @return         names of contained activities
 	ArrayList<String> selectProgram(String program) {
 		return db.query("select name from activity where program is '" + program + "';", "name");
 	}
 
-	// Returns the sum of ECTS points under the given category from the student as a string
+	/// sum of ECTS points under the given category
+	///
+	/// @param program  programme name
+	/// @return         ECTS points as String
 	String getSumEcts(String program){
 		if(program==null)return "0";
 		ArrayList<String> result = db.query("select sum(activity.ects) as total_ects,student.name from student left outer join participation on student.studid = participation.studid inner join activity on participation.indeks = activity.indeks where program is '"+program+"' group by student.studid ;", "total_ects");
 		if (result.isEmpty()) return "0";
 		return result.getFirst();
 	}
+
+	/// sum of ECTS points under the given category
+	///
+	/// @return         names of all activities as list of String
 	ArrayList<String> getAllActivities() {
 		return db.query("select name from activity;", "name");
 	}
diff --git a/src/com.example.portfolio2/module-info.java b/src/com.example.portfolio2/module-info.java
index 7fe280c..4977f2a 100644
--- a/src/com.example.portfolio2/module-info.java
+++ b/src/com.example.portfolio2/module-info.java
@@ -1,3 +1,4 @@
+/// Bachelorizer - bachelor programme registrar
 module com.example.portfolio2 {
     requires javafx.controls;
     requires java.sql;