From 38d76fbcda40ec6fc73a3d5490b44a5f27f30526 Mon Sep 17 00:00:00 2001 From: Jens Pelzetter Date: Fri, 31 Jul 2020 18:30:00 +0200 Subject: [PATCH] Code documentation --- .../src/main/typescript/clients/groups-api.ts | 2 + .../typescript/entities/categorization.ts | 118 ++++++++++++++++-- .../main/typescript/entities/configuration.ts | 22 ++++ .../src/main/typescript/entities/core.ts | 5 + .../src/main/typescript/entities/group.ts | 54 ++++++-- .../src/main/typescript/entities/imexport.ts | 22 ++++ .../src/main/typescript/entities/party.ts | 54 +++++++- .../src/main/typescript/entities/role.ts | 114 ++++++++++++++++- .../src/main/typescript/entities/user.ts | 76 +++++++++++ .../src/main/typescript/entities/workflow.ts | 17 +++ 10 files changed, 460 insertions(+), 24 deletions(-) diff --git a/ccm-core-apiclient/src/main/typescript/clients/groups-api.ts b/ccm-core-apiclient/src/main/typescript/clients/groups-api.ts index 3c9bbd403..b0f10e423 100644 --- a/ccm-core-apiclient/src/main/typescript/clients/groups-api.ts +++ b/ccm-core-apiclient/src/main/typescript/clients/groups-api.ts @@ -78,4 +78,6 @@ export class GroupsApiClient { throw `Failed to get group ${groupIdentifier}: ${err}`; } } + + } diff --git a/ccm-core-apiclient/src/main/typescript/entities/categorization.ts b/ccm-core-apiclient/src/main/typescript/entities/categorization.ts index 5590810a6..070182f46 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/categorization.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/categorization.ts @@ -1,38 +1,130 @@ +/** + * Entities used the categorization API. + * @packageDocumentation + */ + import { LocalizedString, assertProperties, } from "@libreccm/ccm-apiclient-commons"; import { CcmObjectId } from "./core"; -export interface AssociatedCategory { - name: string; - title: LocalizedString; - description: LocalizedString; -} - -export interface Category { +/** + * Data required to identify a category. + */ +export interface CategoryId { categoryId: number; uuid: string; uniqueId: string; name: string; +} + +/** + * An entity providing the data of a category which is associated with + * another category. + */ +export interface AssociatedCategory extends CategoryId { + /** + * The name of the category + */ + name: string; + /** + * The title of the category + */ title: LocalizedString; + /** + * The description of the category + */ description: LocalizedString; +} + +/** + * A category. + */ +export interface Category { + /** + * The ID of the category. + */ + categoryId: number; + /** + * The UUID of the category. + */ + uuid: string; + /** + * The unique ID of the category. + */ + uniqueId: string; + /** + * The name of the category + */ + name: string; + /** + * The title of the category. + */ + title: LocalizedString; + /** + * The description of the category. + */ + description: LocalizedString; + /** + * Is the category enabled? + */ enabled: boolean; + /** + * Is the teh category an abstract category? + */ abstractCategory: boolean; + /** + * The parent category of the category. Is null if the category is a root + * category. + */ parentCategory: AssociatedCategory | null; + /** + * Used to determine the order of the category in the list of subcategories + * of the parent category. + */ categoryOrder: number; } +/** + * Data about a categorized object. + */ export interface Categorization { + /** + * The ID of the categorization. + */ categorizationId: number; + /** + * The UUID of the categorization + */ uuid: string; + /** + * The categorized object. + */ categorizedObject: CcmObjectId; + /** + * Is the categorized object the index object of the category? + */ indexObject: boolean; + /** + * Used to order the list of categories to which an object is assigned. + */ categoryOrder: number; + /** + * Used to order the list of objects assigned to a category. + */ objectOrder: number; + /** + * The type of the categorization. + */ type: string; } +/** + * Builds a {@link Category} object from a `Record`. + * + * @param record The record used as datasource. + */ export function buildCategoryFromRecord( record: Record ): Category { @@ -67,6 +159,12 @@ export function buildCategoryFromRecord( }; } +/** + * Helper function for building a {@link Categorization} object from + * a record. + * + * @param record The record to use as datasource. + */ export function buildCategorizationFromRecord( record: Record ): Categorization { @@ -77,7 +175,7 @@ export function buildCategorizationFromRecord( "indexObject", "categoryOrder", "objectOrder", - "type" + "type", ]); return { @@ -87,6 +185,6 @@ export function buildCategorizationFromRecord( indexObject: record.indexObject as boolean, categoryOrder: record.categoryOrder as number, objectOrder: record.objectOrder as number, - type: record.type as string - } + type: record.type as string, + }; } diff --git a/ccm-core-apiclient/src/main/typescript/entities/configuration.ts b/ccm-core-apiclient/src/main/typescript/entities/configuration.ts index d9c97ab65..1ec90d6fa 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/configuration.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/configuration.ts @@ -1,5 +1,14 @@ +/** + * Entities used by the configuration API. + * + * @packageDocumentation + */ + import { assertProperties } from "@libreccm/ccm-apiclient-commons"; +/** + * Informations about a configuration class. + */ export interface ConfigurationInfo { name: string; descBundle: string; @@ -8,6 +17,9 @@ export interface ConfigurationInfo { settings: Record; } +/** + * Information about a specific setting. + */ export interface SettingInfo { name: string; valueType: string; @@ -18,6 +30,11 @@ export interface SettingInfo { descKey: string; } +/** + * Helper function for building a {@link ConfigurationInfo} object from a + * record. + * @param record The record used as datasource. + */ export function buildConfigurationInfoFromRecord( record: Record ): ConfigurationInfo { @@ -49,6 +66,11 @@ export function buildConfigurationInfoFromRecord( }; } +/** + * Builds a {@link SettingInfo} object from a record. + * + * @param record The record used as data source. + */ export function buildSettingInfoFromRecord( record: Record ): SettingInfo { diff --git a/ccm-core-apiclient/src/main/typescript/entities/core.ts b/ccm-core-apiclient/src/main/typescript/entities/core.ts index a75770a1e..0c4de1485 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/core.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/core.ts @@ -1,3 +1,8 @@ +/** + * Some basic entities + * @packageDocumentation + */ + /** * Basic data about an `CcmObject`. */ diff --git a/ccm-core-apiclient/src/main/typescript/entities/group.ts b/ccm-core-apiclient/src/main/typescript/entities/group.ts index 5fd2cd8c1..0f6367c0d 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/group.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/group.ts @@ -1,25 +1,66 @@ +/** + * Entities used by the RESTful API for managing groups. + * @packageDocumentation + */ + import { assertProperties } from "@libreccm/ccm-apiclient-commons"; import { PartyId, PartyRoleMembership, buildPartyRoleMembershipFromRecord, + buildPartyIdFromRecord } from "./party"; +/** + * A group is used to collect several users. + */ export interface Group { + /** + * The ID of the group. + */ partyId: number; + /** + * The UUID of the group. + */ uuid: string; + /** + * The name of the group. + */ name: string; + /** + * The members of the group. + */ memberships: GroupUserMembership[]; + /** + * The roles assigned to the group. + */ roleMemberships: PartyRoleMembership[]; } +/** + * Data about a user which is a member of a group. + */ export interface GroupUserMembership { + /** + * The ID of the membership. + */ membershipId: number; + /** + * The UUID of the membership. + */ uuid: string; + /** + * The user. + */ user: PartyId; } +/** + * Builds a {@link Group} object from a `Record`. + * + * @param record The record used as datasource. + */ export function buildGroupFromRecord(record: Record): Group { assertProperties(record, [ "partyId", @@ -48,6 +89,10 @@ export function buildGroupFromRecord(record: Record): Group { }; } +/** + * Builds a {@link GroupUserMembership} object from a record. + * @param record The record used as datasource. + */ export function buildGroupUserMembershipFromRecord( record: Record ): GroupUserMembership { @@ -60,12 +105,3 @@ export function buildGroupUserMembershipFromRecord( }; } -function buildPartyIdFromRecord(record: Record): PartyId { - assertProperties(record, ["partyId", "uuid", "name"]); - - return { - partyId: record.partyId as number, - uuid: record.uuid as string, - name: record.name as string, - }; -} diff --git a/ccm-core-apiclient/src/main/typescript/entities/imexport.ts b/ccm-core-apiclient/src/main/typescript/entities/imexport.ts index 03fe0f675..27f8515c2 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/imexport.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/imexport.ts @@ -1,11 +1,33 @@ +/** + * Entities used by the RESTful API for managing imports and exports. + * @packageDocumentation + */ + import { assertProperties } from "@libreccm/ccm-apiclient-commons"; +/** + * An import manifest contains data about an import. + */ export interface ImportManifest { + /** + * The on which the import archive was created. + */ created: Date; + /** + * The URL of the server on which the archive was created. + */ onServer: string; + /** + * The object types included in the archive. + */ types: string[]; } +/** + * Builds a {@link ImportManifest} from a `Record`. + * + * @param record The record used as data source. + */ export function buildImportManifestFromRecord( record: Record ): ImportManifest { diff --git a/ccm-core-apiclient/src/main/typescript/entities/party.ts b/ccm-core-apiclient/src/main/typescript/entities/party.ts index f2524af18..be64ebd2d 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/party.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/party.ts @@ -1,21 +1,52 @@ -import { - assertProperties -} from "@libreccm/ccm-apiclient-commons"; +/** + * Entities used by the RESTful APIs for managing users, groups and roles. + */ + +import { assertProperties } from "@libreccm/ccm-apiclient-commons"; import { RoleId, buildRoleIdFromRecord } from "./role"; +/** + * A party is either a user or a group. + */ export interface PartyId { + /** + * The ID of the party. + */ partyId: number; + /** + * The UUID of the party. + */ uuid: string; + /** + * The name of the party. + */ name: string; } +/** + * A role assigned to a party. + */ export interface PartyRoleMembership { + /** + * The membership ID. + */ membershipId: number; + /** + * The UUID of the membership. + */ uuid: string; + /** + * The assigned role. + */ role: RoleId; } +/** + * Builds a {@link PartyRoleMembership} from a `Record`. + * + * @param record The record used as data source. + */ export function buildPartyRoleMembershipFromRecord( record: Record ): PartyRoleMembership { @@ -27,3 +58,20 @@ export function buildPartyRoleMembershipFromRecord( role: buildRoleIdFromRecord(record.role as Record), }; } + +/** + * Builds a {@link PartyId} from a `Record`. + * + * @param record The record used as datasource. + */ +export function buildPartyIdFromRecord( + record: Record +): PartyId { + assertProperties(record, ["partyId", "uuid", "name"]); + + return { + partyId: record.partyId as number, + uuid: record.uuid as string, + name: record.name as string, + }; +} diff --git a/ccm-core-apiclient/src/main/typescript/entities/role.ts b/ccm-core-apiclient/src/main/typescript/entities/role.ts index 30fdedcf0..c23217bca 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/role.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/role.ts @@ -1,3 +1,8 @@ +/** + * Entities used by the RESTful API for managing roles. + * @packageDocumentation + */ + import { assertProperties, LocalizedString, @@ -7,44 +12,134 @@ import { TaskId } from "./workflow"; import { PartyId } from "./party"; +/** + * A tasks assigned to a role. + */ export interface RoleAssignedTask { + /** + * The ID of the assignment. + */ taskAssignmentId: number; + /** + * The UUID of the assignment. + */ uuid: string; + /** + * The assigned task. + */ task: TaskId; } +/** + * A role which can be assigned to a user or a group. + */ export interface Role { + /** + * The ID of the role. + */ roleId: number; + /** + * The UUID of the role. + */ uuid: string; + /** + * The name of the role. + */ name: string; + /** + * Description of the role. + */ description: LocalizedString; + /** + * Permissions granted to the role. + */ permissions: RolePermission[]; } +/** + * Basic information required to identify a role. + */ export interface RoleId { + /** + * ID of the role. + */ roleId: number; + /** + * UUID of the role. + */ uuid: string; + /** + * Name of the role. + */ name: string; } +/** + * A member of a role. + */ export interface RolePartyMembership { + /** + * The membership ID. + */ membershipId: number; + /** + * UUID of the membership. + */ uuid: string; + /** + * The member. + */ party: PartyId; } +/** + * A permission granted to a role. + */ export interface RolePermission { + /** + * The ID of the permission. + */ permissionId: number; + /** + * UUID of the permission + */ uuid: string; + /** + * The privilege granted by the permission. + */ grantedPrivilege: string; + /** + * Is the permission inherited? + */ inherited: boolean; - object: CcmObjectId; + /** + * The object for which the permission was granted. Might be null. + */ + object: CcmObjectId | null; + /** + * The user which created the permission. + */ creationUser: PartyId; + /** + * Date on which the permission was created. + */ creationDate: Date; + /** + * The IP of the creation user. + */ creationIp: string; - inheritedFrom: CcmObjectId; + /** + * If the permissions is inherited, this property will point to the + * object from which it was inherited. Might be null. + */ + inheritedFrom: CcmObjectId | null; } +/** + * Builds a {@link Role} object from a `Record`. + * + * @param record The record used as data source. + */ export function buildRoleFromRecord(record: Record): Role { assertProperties(record, [ "roleId", @@ -67,6 +162,11 @@ export function buildRoleFromRecord(record: Record): Role { }; } +/** + * Builds a {@link RoleId} object from a `Record`. + * + * @param record The record used as data source. + */ export function buildRoleIdFromRecord(record: Record): RoleId { assertProperties(record, ["roleId", "uuid", "name"]); @@ -77,6 +177,11 @@ export function buildRoleIdFromRecord(record: Record): RoleId { }; } +/** + * Builds a {@link RolePartyMembership} object from a `Record`. + * + * @param record The record used as data source. + */ export function buildRolePartyMembershipFromRecord( record: Record ): RolePartyMembership { @@ -89,6 +194,11 @@ export function buildRolePartyMembershipFromRecord( }; } +/** + * Builds a {@link RolePermission} object from a `Record`. + * + * @param record The record used as data source. + */ export function buildRolePermissionFromRecord( record: Record ): RolePermission { diff --git a/ccm-core-apiclient/src/main/typescript/entities/user.ts b/ccm-core-apiclient/src/main/typescript/entities/user.ts index b477dab27..9772f0d8a 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/user.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/user.ts @@ -1,3 +1,8 @@ +/** + * Entities used by the RESTful API for managing users. + * @packageDocumentation + */ + import { assertProperties } from "@libreccm/ccm-apiclient-commons"; import { @@ -6,32 +11,97 @@ import { buildPartyRoleMembershipFromRecord, } from "./party"; +/** + * Data about an email address. + */ export interface EmailAddress { + /** + * The email address. + */ address: string; + /** + * Is the address bouncing? + */ bouncing: boolean; + /** + * Is the address verified? + */ verified: boolean; } +/** + * A user + */ export interface User { + /** + * The ID of the user. + */ partyId: number; + /** + * The UUID of the user. + */ uuid: string; + /** + * The name of the user. + */ name: string; + /** + * The given name of the user. + */ givenName: string; + /** + * The family name of the user. + */ familyName: string; + /** + * The primary email address of the user + */ primaryEmailAddress: EmailAddress; + /** + * Additional email addresses of the user. + */ emailAddresses: EmailAddress[]; + /** + * Is the user banned? + */ banned: boolean; + /** + * Is a password reset required for the user? + */ passwordResetRequired: boolean; + /** + * The group memberships of the user. + */ groupMemberships: UserGroupMembership[]; + /** + * The role memberships of the user. + */ roleMemberships: PartyRoleMembership[]; } +/** + * Membership of a user in a group. + */ export interface UserGroupMembership { + /** + * The ID of the membership. + */ membershipId: number; + /** + * The UUID of the membership. + */ uuid: string; + /** + * The group. + */ group: PartyId; } +/** + * Builds a {@link User} object from a `Record`. + * + * @param record The record used as data source. + */ export function buildUserFromRecord(record: Record): User { assertProperties(record, [ "partyId", @@ -75,6 +145,12 @@ export function buildUserFromRecord(record: Record): User { }; } +/** + * Builds a {@link UserGroupMembership} object from a `Record`. + * + * @param record The record used as data source. + */ + export function buildUserGroupMembershipFromRecord( record: Record ): UserGroupMembership { diff --git a/ccm-core-apiclient/src/main/typescript/entities/workflow.ts b/ccm-core-apiclient/src/main/typescript/entities/workflow.ts index 9e88c74f3..2bcea053b 100644 --- a/ccm-core-apiclient/src/main/typescript/entities/workflow.ts +++ b/ccm-core-apiclient/src/main/typescript/entities/workflow.ts @@ -1,10 +1,27 @@ +/** + * Entities used by the RESTful API for managing workflows. + * @packageDocumentation + */ + import { LocalizedString, assertProperties, } from "@libreccm/ccm-apiclient-commons"; +/** + * A task associated with another entity. + */ export interface TaskId { + /** + * The id of the task. + */ taskId: number; + /** + * The UUID of the task. + */ uuid: string; + /** + * The label of the task. + */ label: LocalizedString; } \ No newline at end of file