Merge branch 'feature/document-interfaces' into 'develop'

Feature/document interfaces

See merge request !131

backend/src/main/kotlin/io/ticktag/library/hashing/HashingLibrary.kt

@@ -1,6 +1,18 @@
 package io.ticktag.library.hashing
 
 interface HashingLibrary {
+    /**
+     * Library function for hashing passwords so they can be stored in the databse
+     * @param password plain text password
+     * @return hashedPassword
+     */
     fun hashPassword(password: String): String
+
+    /**
+     * Check if password hashed is equal the hash
+     * @param password plain text password, which will be checked
+     * @param hash hash which will be checked
+     * @return true if given password hashed is equal to the given hash, otherwise false
+     */
     fun checkPassword(password: String, hash: String): Boolean
 }

backend/src/main/kotlin/io/ticktag/library/unicode/NameNormalizationLibrary.kt

@@ -1,5 +1,10 @@
 package io.ticktag.library.unicode
 
 interface NameNormalizationLibrary {
+    /**
+     * normalize names so user input can be compared
+     * @param name any name which has to be normalized
+     * @return normalized name
+     */
     fun normalize(name: String): String
 }

backend/src/main/kotlin/io/ticktag/persistence/kanban/KanbanCellRepository.kt

@@ -17,7 +17,5 @@ interface KanbanCellRepository : TicktagCrudRepository<KanbanCell, UUID> {
             "ORDER BY k.order")
     fun findByTicketTagId(@Param("tagId") tagId: UUID): List<Ticket>
 
-
-
     fun deleteByTagId(tagId: UUID)
 }

backend/src/main/kotlin/io/ticktag/service/assignmenttag/AssignmentTagService.kt

@@ -7,9 +7,34 @@ import io.ticktag.service.assignmenttag.dto.UpdateAssignmentTag
 import java.util.*
 
 interface AssignmentTagService {
+    /**
+     * create an assignment Tag and store it into the database.
+     * An assignment Tag can be used to tag an assignment between a user and a ticket
+     * @param projectId id of the project where the tag will be stored
+     * @param createAssignmentTag DTO which encapsulates the properties of an assignmentTag
+     * @return the created assignmentTag encapsulated in an AssignmentTagResult
+     */
     fun createAssignmentTag(projectId: UUID, createAssignmentTag: CreateAssignmentTag): AssignmentTagResult
+
+    /**
+     * Find a specific Assignment Tag
+     * @param id id of the object to find - if this is id is not available there will be an exception.
+     */
     fun getAssignmentTag(id: UUID): AssignmentTagResult
+    /**
+     * Update a specific Assignment Tag
+     * @param id id of the object to updated - if this is id is not available there will be an exception.
+     * @param updateAssignmentTag properties of an AssignmentTag encapsulated
+     */
     fun updateAssignmentTag(id: UUID, updateAssignmentTag: UpdateAssignmentTag): AssignmentTagResult
+
+    /**
+     * retuns a list of all AssignmentTags in a project
+     */
     fun listAssignmentTags(projectId: UUID): List<AssignmentTagResult>
+
+    /**
+     * diables a assignmentTag so it can't be used anymore
+     */
     fun deleteAssignmentTag(id: UUID)
 }

backend/src/main/kotlin/io/ticktag/service/comment/service/CommentService.kt

@@ -8,7 +8,23 @@ import java.util.*
 
 
 interface CommentService {
+    /**
+     * List all comments for a specific ticket
+     * @param ticketId if there is no ticket with this id an exception will be thrown
+     */
     fun listCommentsForTicket(ticketId: UUID): List<CommentResult>
+
+    /**
+     * Get a specific Comment with this ID
+     * @param commentId if there is no comment with this id an exception will be thrown
+     */
     fun getComment(commentId: UUID): CommentResult?
+
+    /**
+     * create Comment and store into Database
+     * @param createComment properties of a comment encapsulated into a DTO
+     * @param principal security principal
+     * @param ticketId id of the ticket, where the comment will be added
+     */
     fun createComment(createComment: CreateComment, principal: Principal, ticketId: UUID): CommentResult
 }

backend/src/main/kotlin/io/ticktag/service/fallbackadmin/services/FallbackAdminService.kt

@@ -1,5 +1,8 @@
 package io.ticktag.service.fallbackadmin.services
 
 interface FallbackAdminService {
+    /**
+     * Function will be used to ensure that there is always an admin
+     */
     fun ensureAdminExists()
 }

backend/src/main/kotlin/io/ticktag/service/kanbanboard/services/KanbanService.kt

@@ -10,6 +10,11 @@ import java.util.*
 
 
 interface KanbanService {
+    /**
+     * List all columns of a kanbanBoard with their tickets.
+     * A column is equal to a Tag of a exclusive Tag group.
+     * This list will be filtered acoriding to the paramters.
+     */
     fun listColumns(kanbanBoardId: UUID,
                     numbers: List<Int>?,
                     title: String?,
@@ -27,8 +32,30 @@ interface KanbanService {
                     open: Boolean?,
                     parent: Int?): List<KanbanColumnResult>
 
+    /**
+     * List all available Kanbanboards of a project.
+     * A kanbanboard is always an exclusive Tag Group
+     */
     fun listBoards(projectId: UUID): List<KanbanBoardResult>
-    fun updateKanbanBoard(columns: UpdateKanbanColumn, principal: Principal, id: UUID)
+
+    /**
+     * Updates a Column of the Kanbanboard
+     * In the UpdateKanbanColumn will be a list of the tickets in a new sort.
+     * For each action updateKanbanBoard has to be updated once.
+     * If a ticket will be tragged to a new column, the id of the new column has to be provided.
+     * @param column an encapsulated Object of the properties which will be updated
+     * @param principal security principal
+     * @param id id of the Tag/Columns
+     */
+    fun updateKanbanBoard(column: UpdateKanbanColumn, principal: Principal, id: UUID)
+
+    /**
+     * Get a KanbanBoard result
+     */
     fun getBoard(boardId: UUID): KanbanBoardResult
+
+    /**
+     * For the given ticketId, all subtickets will be inserted below the specified ticket.
+     */
     fun collectSubticket(ticketId: UUID, tagId: UUID, principal: Principal)
 }

backend/src/main/kotlin/io/ticktag/service/loggedtime/service/LoggedTimeService.kt

@@ -8,10 +8,35 @@ import java.util.*
 
 
 interface LoggedTimeService {
+    /**
+     * List all loggedTime elements of a comment
+     */
     fun listLoggedTimeForComment(commentId: UUID): List<LoggedTimeResult>
+
+    /**
+     * List all logged Time Objects for a project and use and a category(Time Category)
+     */
     fun listLoggedTimeForProjectAndUserAndCategory(projedId: UUID?, userId: UUID?, categoryId: UUID?): List<LoggedTimeResult>
+
+    /**
+     * create a Logged Time Object for a comment.
+     * Logged Time have to be always related to a Comment.
+     */
     fun createLoggedTime(createLoggedTime: CreateLoggedTime, commentId: UUID): LoggedTimeResult
+
+    /**
+     * Update a Logged Time Object
+     */
     fun updateLoggedTime(updateLoggedTime: UpdateLoggedTime, loggedTimeId: UUID): LoggedTimeResult
+
+    /**
+     * Get a specific LoggedTime Object
+     */
     fun getLoggedTime(loggedTimeId: UUID): LoggedTimeResult
+
+    /**
+     * Get Logged Time Objects with the given Ids.
+     * This Function will be used to resolve nested Objects.
+     */
     fun getLoggedTimes(ids: List<UUID>, principal: Principal): Map<UUID, LoggedTimeResult>
 }

backend/src/main/kotlin/io/ticktag/service/member/MemberService.kt

@@ -6,8 +6,24 @@ import io.ticktag.service.member.dto.UpdateMember
 import java.util.*
 
 interface MemberService {
+    /**
+     * get a member. A member is a user who is working at a project
+     */
     fun getMember(userId: UUID, projectId: UUID): MemberResult
+
+    /**
+     * create a member. Therefore an existing User can contribute to a project
+     */
     fun createMember(userId: UUID, projectId: UUID, createMember: CreateMember): MemberResult
+
+    /**
+     * The member won't be deleted, his role will be removed and so he can't contributed to the Project anymore
+     * All entities related to this member will still exist after the deletion
+     */
     fun deleteMember(userId: UUID, projectId: UUID)
+
+    /**
+     * Update a role or a default assignment Tag for a member (A user in a project)
+     */
     fun updateMember(userId: UUID, projectId: UUID, member: UpdateMember): MemberResult
 }

backend/src/main/kotlin/io/ticktag/service/project/services/ProjectService.kt

@@ -9,11 +9,38 @@ import org.springframework.data.domain.Pageable
 import java.util.*
 
 interface ProjectService {
+    /**
+     * Get a Project with specified UUID if it exits
+     */
     fun getProject(id: UUID): ProjectResult?
+
+    /**
+     * List all Projects
+     */
     fun listAllProjects(name: String, disabled: Boolean, pageable: Pageable): Page<ProjectResult>
+
+    /**
+     * List all projects where a given User is a member
+     */
     fun listUserProjects(userId: UUID, name: String, disabled: Boolean, pageable: Pageable): Page<ProjectResult>
+
+    /**
+     * Create a project with given properties
+     */
     fun createProject(project: CreateProject): ProjectResult
+
+    /**
+     * Deletes a project permanently
+     */
     fun deleteProject(id: UUID)
+
+    /**
+     * Updates the properties of a project
+     */
     fun updateProject(id: UUID, project: UpdateProject): ProjectResult
+
+    /**
+     * List all projects roles of a project
+     */
     fun listProjectRoles(): List<ProjectRoleResult>
 }

backend/src/main/kotlin/io/ticktag/service/statistic/service/StatisticService.kt

@@ -6,6 +6,13 @@ import java.util.*
 
 
 interface StatisticService {
+    /**
+     * Returns all Progresses of each submitted TicketId
+     */
     fun getTicketProgresses(ids: Collection<UUID>, principal: Principal): Map<UUID, TicketProgressResult>
+
+    /**
+     * Get Progress of one ticket
+     */
     fun getTicketProgress(id: UUID): TicketProgressResult
 }

backend/src/main/kotlin/io/ticktag/service/ticket/service/TicketService.kt

@@ -9,6 +9,9 @@ import java.util.*
 
 
 interface TicketService {
+    /**
+     * List all Tickets for a project with given filters
+     */
     fun listTicketsOverview(project: UUID,
                     numbers: List<Int>?,
                     title: String?,
@@ -27,14 +30,49 @@ interface TicketService {
                     parent: Int?,
                     pageable: Pageable): Page<TicketOverviewResult>
 
+    /**
+     * List Tickets with paging
+     */
     fun listTickets(project: UUID, pageable: Pageable): Page<TicketResult>
+
+    /**
+     * Get one Ticket
+     */
     fun getTicket(id: UUID): TicketResult
+
+    /**
+     * Get a ticket with the ticket id, which is unique for each project
+     */
     fun getTicket(projectId: UUID, ticketNumber: Int): TicketResult
+
+    /**
+     * get all tickets for the supplied ids.
+     */
     fun getTickets(ids: Collection<UUID>, principal: Principal): Map<UUID, TicketResult>
+
+    /**
+     * create a ticket
+     */
     fun createTicket(createTicket: CreateTicket, principal: Principal, projectId: UUID): TicketResult
+
+    /**
+     * update a ticket with Properties encapsulated in an Object
+     */
     fun updateTicket(updateTicket: UpdateTicket, ticketId: UUID, principal: Principal): TicketResult
+
+    /**
+     * Delete a ticket
+     */
     fun deleteTicket(id: UUID)
+
+    /**
+     * list a few Tickets. this function will be used for autocompletion
+     */
     fun listTicketsFuzzy(project: UUID, query: String, pageable: Pageable): List<TicketResult>
+
+    /**
+     * List tickets with story points. Similar to listTicketOverview but only for Storypoints
+     */
     fun listTicketsStoryPoints(project: UUID,
                                numbers: List<Int>?,
                                title: String?,

backend/src/main/kotlin/io/ticktag/service/ticketassignment/services/TicketAssignmentService.kt

@@ -5,9 +5,28 @@ import io.ticktag.service.ticketassignment.dto.TicketAssignmentResult
 import java.util.*
 
 interface TicketAssignmentService {
+    /**
+     * Get the an assigned user for a Tickets
+     */
     fun getTicketAssignment(ticketId: UUID, tagId: UUID, userId: UUID): TicketAssignmentResult
+
+    /**
+     * Assign a User to a ticket
+     */
     fun createTicketAssignment(ticketId: UUID, tagId: UUID, userId: UUID, principal: Principal): TicketAssignmentResult
+
+    /**
+     * Similar to creatTicketAssignment but only creates ticket if it not already exits
+     */
     fun createOrGetIfExistsTicketAssignment(ticketId: UUID, tagId: UUID, userId: UUID, principal: Principal): TicketAssignmentResult
+
+    /**
+     * Delete a User assignment to a Ticket
+     */
     fun deleteTicketAssignment(ticketId: UUID, tagId: UUID, userId: UUID, principal: Principal)
+
+    /**
+     * Delete all Assignments of a User to a ticket
+     */
     fun deleteTicketAssignments(ticketId: UUID, userId: UUID, principal: Principal)
 }

backend/src/main/kotlin/io/ticktag/service/ticketevent/services/TicketEventService.kt

@@ -5,6 +5,13 @@ import io.ticktag.service.ticketevent.dto.TicketEventResult
 import java.util.*
 
 interface TicketEventService {
+    /**
+     * List ticket events (History of a Ticket) for a given Ticket ID
+     */
     fun listTicketEvents(ticketId: UUID): List<TicketEventResult>
+
+    /**
+     * List all Events regarding a state change
+     */
     fun findAllStateChangedEvents(ticketIds: List<UUID>, principal: Principal): List<TicketEventResult>
 }