Remove implementation notes from API documentation

Reasons:
* not used consistently
* Java signatures are not helpful
* Return type should not be hard-coded in a String

Statistics model now correctly uses value instead of notes for
documentation of properties.

src/main/java/de/thm/arsnova/controller/AudienceQuestionController.java

@@ -58,8 +58,7 @@ public class AudienceQuestionController extends PaginationController {
 	private IQuestionService questionService;
 
 	@ApiOperation(value = "Count all the questions in current session",
-			nickname = "getAudienceQuestionCount",
-			notes = "getInterposedCount(String sessionkey, String user)")
+			nickname = "getAudienceQuestionCount")
 	@RequestMapping(value = "/count", method = RequestMethod.GET)
 	@DeprecatedApi
 	@Deprecated
@@ -68,8 +67,7 @@ public class AudienceQuestionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "count all unread interposed questions",
-			nickname = "getUnreadInterposedCount",
-			notes = "getUnreadInterposedCount(String sessionkey, String user)")
+			nickname = "getUnreadInterposedCount")
 	@RequestMapping(value = "/readcount", method = RequestMethod.GET)
 	@DeprecatedApi
 	@Deprecated
@@ -78,8 +76,7 @@ public class AudienceQuestionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "Retrieves all Interposed Questions for a Session",
-			nickname = "getInterposedQuestions",
-			notes = "Repsonse structure: InterposedQuestion[], encoding-type: application/json")
+			nickname = "getInterposedQuestions")
 	@RequestMapping(value = "/", method = RequestMethod.GET)
 	@Pagination
 	public List<InterposedQuestion> getInterposedQuestions(@ApiParam(value = "Session-Key from current session", required = true) @RequestParam final String sessionkey) {
@@ -87,16 +84,14 @@ public class AudienceQuestionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "Retrieves an InterposedQuestion",
-			nickname = "getInterposedQuestion",
-			notes = "Repsonse structure: InterposedQuestion, encoding-type: application/json")
+			nickname = "getInterposedQuestion")
 	@RequestMapping(value = "/{questionId}", method = RequestMethod.GET)
 	public InterposedQuestion getInterposedQuestion(@ApiParam(value = "ID of the question that needs to be deleted", required = true) @PathVariable final String questionId) {
 		return new InterposedQuestion(questionService.readInterposedQuestion(questionId));
 	}
 
 	@ApiOperation(value = "Creates a new Interposed Question for a Session and returns the InterposedQuestion's data",
-			nickname = "postInterposedQuestion",
-			notes = "Repsonse structure: InterposedQuestion, encoding-type: application/json")
+			nickname = "postInterposedQuestion")
 	@ApiResponses(value = {
 		@ApiResponse(code = 400, message = "Bad Request - The Api cannot or will not process the request due to something that is perceived to be a client error")
 	})
@@ -114,8 +109,7 @@ public class AudienceQuestionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "Deletes an InterposedQuestion",
-			nickname = "deleteInterposedQuestion",
-			notes = "Repsonse structure: none, encoding-type: application/json")
+			nickname = "deleteInterposedQuestion")
 	@RequestMapping(value = "/{questionId}", method = RequestMethod.DELETE)
 	public void deleteInterposedQuestion(@ApiParam(value = "ID of the question that needs to be deleted", required=true) @PathVariable final String questionId) {
 		questionService.deleteInterposedQuestion(questionId);

src/main/java/de/thm/arsnova/controller/CourseController.java

@@ -60,10 +60,7 @@ public class CourseController extends AbstractController {
 	private IUserService userService;
 
 	@ApiOperation(value = "retrieves a User Courses",
-			nickname = "myCourses",
-			notes = "myCourses(" +
-			"@ApiParam(value=\"sort my courses by name\", required=true)" +
-			"@RequestParam(value = \"sortby\", defaultValue = \"name\") final String sortby)")
+			nickname = "myCourses")
 	@ApiResponses(value = {
 		@ApiResponse(code = 200, message = "successful API requests")
 	})

src/main/java/de/thm/arsnova/controller/FeedbackController.java

@@ -59,8 +59,7 @@ public class FeedbackController extends AbstractController {
 	private IUserService userService;
 
 	@ApiOperation(value = "Get feedback from a session",
-			nickname = "getFeedback",
-			notes = "getFeedback(@PathVariable final String sessionkey)")
+			nickname = "getFeedback")
 	@DeprecatedApi
 	@Deprecated
 	@RequestMapping(value = "/session/{sessionkey}/feedback", method = RequestMethod.GET)
@@ -69,8 +68,7 @@ public class FeedbackController extends AbstractController {
 	}
 
 	@ApiOperation(value = "Get own feedback from a session",
-			nickname = "getMyFeedback",
-			notes = "getMyFeedback(@PathVariable final String sessionkey)")
+			nickname = "getMyFeedback")
 	@ApiResponses(value = {
 		@ApiResponse(code = 404, message = "Not Found - The requested resource could not be found but may be available again in the future.")
 	})
@@ -86,8 +84,7 @@ public class FeedbackController extends AbstractController {
 	}
 
 	@ApiOperation(value = "Get amout of feedback from a session",
-			nickname = "getFeedbackCount",
-			notes = "getFeedbackCount(@PathVariable final String sessionkey)")
+			nickname = "getFeedbackCount")
 	@DeprecatedApi
 	@Deprecated
 	@RequestMapping(value = "/session/{sessionkey}/feedbackcount", method = RequestMethod.GET)
@@ -96,8 +93,7 @@ public class FeedbackController extends AbstractController {
 	}
 
 	@ApiOperation(value = "Get the average feedback (rounded) from a session",
-			nickname = "getAverageFeedbackRounded",
-			notes = "getAverageFeedbackRounded(@PathVariable final String sessionkey)")
+			nickname = "getAverageFeedbackRounded")
 	@DeprecatedApi
 	@Deprecated
 	@RequestMapping(value = "/session/{sessionkey}/roundedaveragefeedback", method = RequestMethod.GET)
@@ -113,10 +109,7 @@ public class FeedbackController extends AbstractController {
 	}
 
 	@ApiOperation(value = "Post feedback for a session",
-			nickname = "postFeedback",
-			notes = "postFeedback(" +
-			"@PathVariable final String sessionkey," +
-			"@RequestBody final int value)")
+			nickname = "postFeedback")
 	@ApiResponses(value = {
 		@ApiResponse(code = 404, message = "Not Found - The requested resource could not be found but may be available again in the future.")
 	})

src/main/java/de/thm/arsnova/controller/SessionController.java

@@ -75,24 +75,21 @@ public class SessionController extends PaginationController {
 	private IUserService userService;
 
 	@ApiOperation(value = "Count all the questions in current session",
-			nickname = "joinSession",
-			notes = "Repsonse structure: none, encoding-type: application/json")
+			nickname = "joinSession")
 	@RequestMapping(value = "/{sessionkey}", method = RequestMethod.GET)
 	public Session joinSession(@ApiParam(value = "Session-Key from current session", required = true) @PathVariable final String sessionkey) {
 		return Session.anonymizedCopy(sessionService.getSession(sessionkey));
 	}
 
 	@ApiOperation(value = "deletes a session",
-			nickname = "deleteSession",
-			notes = "Repsonse structure: none, encoding-type: application/json")
+			nickname = "deleteSession")
 	@RequestMapping(value = "/{sessionkey}", method = RequestMethod.DELETE)
 	public void deleteSession(@ApiParam(value = "Session-Key from current session", required = true) @PathVariable final String sessionkey) {
 		sessionService.deleteSession(sessionkey);
 	}
 
 	@ApiOperation(value = "count active users",
-			nickname = "countActiveUsers",
-			notes = "countActiveUsers(@ApiParam(value = \"Session-Key from current session\", required = true)")
+			nickname = "countActiveUsers")
 	@DeprecatedApi
 	@Deprecated
 	@RequestMapping(value = "/{sessionkey}/activeusercount", method = RequestMethod.GET)
@@ -101,8 +98,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "Creates a new Session and returns the Session's data",
-			nickname = "postNewSession",
-			notes = "Repsonse structure: Session, encoding-type: application/json")
+			nickname = "postNewSession")
 	@ApiResponses(value = {
 		@ApiResponse(code = 201, message = "The request has been fulfilled and resulted in a new resource being created"),
 		@ApiResponse(code = 503, message = "Service Unavailable - The Api is currently unavailable (because it is overloaded or down for maintenance)")
@@ -134,8 +130,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "updates a session",
-			nickname = "postNewSession",
-			notes = "Request encoding: none, Repsonse structure: Session, encoding-type: application/json")
+			nickname = "postNewSession")
 	@RequestMapping(value = "/{sessionkey}", method = RequestMethod.PUT)
 	public Session updateSession(
 			@ApiParam(value = "session-key from current session", required = true) @PathVariable final String sessionkey,
@@ -145,8 +140,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "Retrieves a list of Sessions",
-			nickname = "getSessions",
-			notes = "Request encoding: Query string, Repsonse structure: Session[], encoding-type: application/json")
+			nickname = "getSessions")
 	@ApiResponses(value = {
 		@ApiResponse(code = 204, message = "No Content - successfully processed the request"),
 		@ApiResponse(code = 501, message = "Not implemented - The Api either does not recognize the request method, or it lacks the ability to fulfil the request")
@@ -196,8 +190,7 @@ public class SessionController extends PaginationController {
 	 * @return
 	 */
 	@ApiOperation(value = "Retrieves a Session",
-			nickname = "getMySessions",
-			notes = "Request encoding: none, Repsonse structure: Session, encoding-type: application/json")
+			nickname = "getMySessions")
 	@ApiResponses(value = {
 		@ApiResponse(code = 204, message = "No Content - successfully processed the request")
 	})
@@ -229,8 +222,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "Retrieves all public pool sessions for the current user",
-			nickname = "getMyPublicPoolSessions",
-			notes = "Request encoding: none, Repsonse structure: Session[], encoding-type: application/json")
+			nickname = "getMyPublicPoolSessions")
 	@ApiResponses(value = {
 		@ApiResponse(code = 204, message = "No Content - successfully processed the request")
 	})
@@ -249,8 +241,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "Retrieves all public pool sessions",
-			nickname = "getMyPublicPoolSessions",
-			notes = "Request encoding: none, Repsonse structure: Session[], encoding-type: application/json")
+			nickname = "getMyPublicPoolSessions")
 	@ApiResponses(value = {
 		@ApiResponse(code = 204, message = "No Content - successfully processed the request")
 	})
@@ -269,8 +260,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "imports a session",
-			nickname = "importSession",
-			notes = "Request encoding: none, Repsonse structure: Session[], encoding-type: application/json")
+			nickname = "importSession")
 	@RequestMapping(value = "/import", method = RequestMethod.POST)
 	public SessionInfo importSession(
 			@ApiParam(value = "current session", required = true) @RequestBody final ImportExportSession session,
@@ -280,8 +270,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "Locks or unlocks a Session",
-			nickname = "lockSession",
-			notes = "Request encoding: Query string, Repsonse structure: Session, encoding-type: application/json")
+			nickname = "lockSession")
 	@ApiResponses(value = {
 		@ApiResponse(code = 404, message = "Not Found - The requested resource could not be found but may be available again in the future")
 	})
@@ -299,8 +288,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "retrieves a value for the learning progress",
-			nickname = "learningProgress",
-			notes = "Request encoding: none, Repsonse structure: LearningProgressValues[], encoding-type: application/json")
+			nickname = "learningProgress")
 	@RequestMapping(value = "/{sessionkey}/learningprogress", method = RequestMethod.GET)
 	public LearningProgressValues learningProgress(
 			@ApiParam(value = "session-key from current session", required = true) @PathVariable final String sessionkey,
@@ -312,8 +300,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "retrieves a value for the learning progress for the current user",
-			nickname = "myLearningProgress",
-			notes = "Request encoding: none, Repsonse structure: LearningProgressValues, encoding-type: application/json")
+			nickname = "myLearningProgress")
 	@RequestMapping(value = "/{sessionkey}/mylearningprogress", method = RequestMethod.GET)
 	public LearningProgressValues myLearningProgress(
 			@ApiParam(value = "session-key from current session", required = true) @PathVariable final String sessionkey,
@@ -325,8 +312,7 @@ public class SessionController extends PaginationController {
 	}
 
 	@ApiOperation(value = "retrieves all session features",
-			nickname = "sessionFeatures",
-			notes = "Request encoding: none, Repsonse structure: SessionFeature, encoding-type: application/json")
+			nickname = "sessionFeatures")
 	@RequestMapping(value = "/{sessionkey}/features", method = RequestMethod.GET)
 	public SessionFeature sessionFeatures(
 			@ApiParam(value = "session-key from current session", required = true) @PathVariable final String sessionkey,
@@ -337,8 +323,7 @@ public class SessionController extends PaginationController {
 
 	@RequestMapping(value = "/{sessionkey}/features", method = RequestMethod.PUT)
 	@ApiOperation(value = "change all session features",
-			nickname = "changeSessionFeatures",
-			notes = "Request encoding: none, Repsonse structure: SessionFeature, encoding-type: application/json")
+			nickname = "changeSessionFeatures")
 	public SessionFeature changeSessionFeatures(
 			@ApiParam(value = "session-key from current session", required = true) @PathVariable final String sessionkey,
 			@ApiParam(value = "session feature", required = true) @RequestBody final SessionFeature features,

src/main/java/de/thm/arsnova/controller/SocketController.java

@@ -63,8 +63,7 @@ public class SocketController extends AbstractController {
 	private static final Logger LOGGER = LoggerFactory.getLogger(SocketController.class);
 
 	@ApiOperation(value = "requested to assign Websocket session",
-			nickname = "authorize",
-			notes = "Request encoding: none, Repsonse structure: none, encoding-type: application/json")
+			nickname = "authorize")
 	@ApiResponses(value = {
 		@ApiResponse(code = 204, message = "No Content - successfully processed the request"),
 		@ApiResponse(code = 400, message = "Bad Request - The Api cannot or will not process the request due to something that is perceived to be a client error"),
@@ -90,8 +89,7 @@ public class SocketController extends AbstractController {
 	}
 
 	@ApiOperation(value = "retrieves a socket url",
-			nickname = "getSocketUrl",
-			notes = "Request encoding: none, Repsonse structure: none, encoding-type: application/json")
+			nickname = "getSocketUrl")
 	@RequestMapping(value = "/url", method = RequestMethod.GET)
 	public String getSocketUrl(final HttpServletRequest request) {
 		StringBuilder url = new StringBuilder();

src/main/java/de/thm/arsnova/controller/StatisticsController.java

@@ -41,8 +41,7 @@ public class StatisticsController extends AbstractController {
 	private IStatisticsService statisticsService;
 
 	@ApiOperation(value = "Retrieves global statistics",
-			nickname = "getStatistics",
-			notes = "getStatistics()")
+			nickname = "getStatistics")
 	@RequestMapping(method = RequestMethod.GET, value = "/statistics")
 	@CacheControl(maxAge = 60, policy = CacheControl.Policy.PUBLIC)
 	public Statistics getStatistics() {
@@ -50,8 +49,7 @@ public class StatisticsController extends AbstractController {
 	}
 
 	@ApiOperation(value = "Retrieves the amount of all active users",
-			nickname = "countActiveUsers",
-			notes = "countActiveUsers()")
+			nickname = "countActiveUsers")
 	@DeprecatedApi
 	@Deprecated
 	@RequestMapping(method = RequestMethod.GET, value = "/statistics/activeusercount", produces = "text/plain")
@@ -60,8 +58,7 @@ public class StatisticsController extends AbstractController {
 	}
 
 	@ApiOperation(value = "Retrieves the amount of all currently logged in users",
-			nickname = "countLoggedInUsers",
-			notes = "countLoggedInUsers()")
+			nickname = "countLoggedInUsers")
 	@DeprecatedApi
 	@Deprecated
 	@RequestMapping(method = RequestMethod.GET, value = "/statistics/loggedinusercount", produces = "text/plain")
@@ -70,8 +67,7 @@ public class StatisticsController extends AbstractController {
 	}
 
 	@ApiOperation(value = "Retrieves the total amount of all sessions",
-			nickname = "countSessions",
-			notes = "countSessions()")
+			nickname = "countSessions")
 	@DeprecatedApi
 	@Deprecated
 	@RequestMapping(method = RequestMethod.GET, value = "/statistics/sessioncount", produces = "text/plain")

src/main/java/de/thm/arsnova/entities/Statistics.java

@@ -38,7 +38,7 @@ public class Statistics {
 	private int interposedQuestions;
 	private int conceptQuestions;
 
-	@ApiModelProperty(required = true, notes = "used to display Answers")
+	@ApiModelProperty(required = true, value = "used to display Answers")
 	public int getAnswers() {
 		return answers;
 	}
@@ -47,7 +47,7 @@ public class Statistics {
 		this.answers = answers;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display Lecture Questions")
+	@ApiModelProperty(required = true, value = "used to display Lecture Questions")
 	public int getLectureQuestions() {
 		return lectureQuestions;
 	}
@@ -56,7 +56,7 @@ public class Statistics {
 		this.lectureQuestions = questions;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display prepartion Questions")
+	@ApiModelProperty(required = true, value = "used to display prepartion Questions")
 	public int getPreparationQuestions() {
 		return preparationQuestions;
 	}
@@ -65,12 +65,12 @@ public class Statistics {
 		this.preparationQuestions = questions;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display Questions")
+	@ApiModelProperty(required = true, value = "used to display Questions")
 	public int getQuestions() {
 		return getLectureQuestions() + getPreparationQuestions();
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display open Sessions")
+	@ApiModelProperty(required = true, value = "used to display open Sessions")
 	public int getOpenSessions() {
 		return openSessions;
 	}
@@ -79,7 +79,7 @@ public class Statistics {
 		this.openSessions = openSessions;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display closed Sessions")
+	@ApiModelProperty(required = true, value = "used to display closed Sessions")
 	public int getClosedSessions() {
 		return closedSessions;
 	}
@@ -88,12 +88,12 @@ public class Statistics {
 		this.closedSessions = closedSessions;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display Sessions")
+	@ApiModelProperty(required = true, value = "used to display Sessions")
 	public int getSessions() {
 		return getOpenSessions() + getClosedSessions();
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display Active Users")
+	@ApiModelProperty(required = true, value = "used to display Active Users")
 	public int getActiveUsers() {
 		return activeUsers;
 	}
@@ -102,7 +102,7 @@ public class Statistics {
 		this.activeUsers = activeUsers;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display logged in Users")
+	@ApiModelProperty(required = true, value = "used to display logged in Users")
 	public int getLoggedinUsers() {
 		return loggedinUsers;
 	}
@@ -111,7 +111,7 @@ public class Statistics {
 		this.loggedinUsers = loggedinUsers;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display interposed Questions")
+	@ApiModelProperty(required = true, value = "used to display interposed Questions")
 	public int getInterposedQuestions() {
 		return interposedQuestions;
 	}
@@ -120,7 +120,7 @@ public class Statistics {
 		this.interposedQuestions = interposedQuestions;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display creators")
+	@ApiModelProperty(required = true, value = "used to display creators")
 	public int getCreators() {
 		return creators;
 	}
@@ -129,7 +129,7 @@ public class Statistics {
 		this.creators = creators;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display concept Questions")
+	@ApiModelProperty(required = true, value = "used to display concept Questions")
 	public int getConceptQuestions() {
 		return conceptQuestions;
 	}
@@ -138,7 +138,7 @@ public class Statistics {
 		this.conceptQuestions = conceptQuestions;
 	}
 
-	@ApiModelProperty(required = true, notes = "used to display active Students")
+	@ApiModelProperty(required = true, value = "used to display active Students")
 	public int getActiveStudents() {
 		return activeStudents;
 	}