Code documentation

Former-commit-id: 38d76fbcda

ccm-core-apiclient/src/main/typescript/clients/groups-api.ts

@@ -78,4 +78,6 @@ export class GroupsApiClient {
             throw `Failed to get group ${groupIdentifier}: ${err}`;
         }
     }
+
+    
 }

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;
+ * Data required to identify a category.
-    title: LocalizedString;
+ */
-    description: LocalizedString;
+export interface CategoryId {
-}
-
-export interface Category {
     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<string, unknown>
 ): 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<string, unknown>
 ): 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,
-    }
+    };
 }

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<string, SettingInfo>;
 }
 
+/**
+ * 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<string, unknown>
 ): 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<string, unknown>
 ): SettingInfo {

ccm-core-apiclient/src/main/typescript/entities/core.ts

@@ -1,3 +1,8 @@
+/**
+ * Some basic entities
+ * @packageDocumentation
+ */
+
 /**
  * Basic data about an `CcmObject`.
  */

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<string, unknown>): Group {
     assertProperties(record, [
         "partyId",
@@ -48,6 +89,10 @@ export function buildGroupFromRecord(record: Record<string, unknown>): Group {
     };
 }
 
+/**
+ * Builds a {@link GroupUserMembership} object from a record.
+ * @param record The record used as datasource.
+ */
 export function buildGroupUserMembershipFromRecord(
     record: Record<string, unknown>
 ): GroupUserMembership {
@@ -60,12 +105,3 @@ export function buildGroupUserMembershipFromRecord(
     };
 }
 
-function buildPartyIdFromRecord(record: Record<string, unknown>): PartyId {
-    assertProperties(record, ["partyId", "uuid", "name"]);
-
-    return {
-        partyId: record.partyId as number,
-        uuid: record.uuid as string,
-        name: record.name as string,
-    };
-}

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<string, unknown>
 ): ImportManifest {

ccm-core-apiclient/src/main/typescript/entities/party.ts

@@ -1,21 +1,52 @@
-import {
+/**
-    assertProperties
+ * Entities used by the RESTful APIs for managing users, groups and roles.
-} from "@libreccm/ccm-apiclient-commons";
+ */
+
+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<string, unknown>
 ): PartyRoleMembership {
@@ -27,3 +58,20 @@ export function buildPartyRoleMembershipFromRecord(
         role: buildRoleIdFromRecord(record.role as Record<string, unknown>),
     };
 }
+
+/**
+ * Builds a {@link PartyId} from a `Record`.
+ * 
+ * @param record The record used as datasource.
+ */
+export function buildPartyIdFromRecord(
+    record: Record<string, unknown>
+): PartyId {
+    assertProperties(record, ["partyId", "uuid", "name"]);
+
+    return {
+        partyId: record.partyId as number,
+        uuid: record.uuid as string,
+        name: record.name as string,
+    };
+}

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<string, unknown>): Role {
     assertProperties(record, [
         "roleId",
@@ -67,6 +162,11 @@ export function buildRoleFromRecord(record: Record<string, unknown>): Role {
     };
 }
 
+/**
+ * Builds a {@link RoleId} object from a `Record`.
+ * 
+ * @param record The record used as data source.
+ */
 export function buildRoleIdFromRecord(record: Record<string, unknown>): RoleId {
     assertProperties(record, ["roleId", "uuid", "name"]);
 
@@ -77,6 +177,11 @@ export function buildRoleIdFromRecord(record: Record<string, unknown>): RoleId {
     };
 }
 
+/**
+ * Builds a {@link RolePartyMembership} object from a `Record`.
+ * 
+ * @param record The record used as data source.
+ */
 export function buildRolePartyMembershipFromRecord(
     record: Record<string, unknown>
 ): 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<string, unknown>
 ): RolePermission {

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<string, unknown>): User {
     assertProperties(record, [
         "partyId",
@@ -75,6 +145,12 @@ export function buildUserFromRecord(record: Record<string, unknown>): User {
     };
 }
 
+/**
+ * Builds a {@link UserGroupMembership} object from a `Record`.
+ * 
+ * @param record The record used as data source.
+ */
+
 export function buildUserGroupMembershipFromRecord(
     record: Record<string, unknown>
 ): UserGroupMembership {

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;
 }