diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index d0433d18ccf..726e0b2dd9d 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -170,7 +170,7 @@ This section describes some noteworthy details, alongside considerations and con ### 4.1. Design considerations: #### 4.1.1. Employee -An important design consideration to note for Employee is the multiple different fields that qualify as candidate _keys_, such as an employee id, email address, and phone number. +An important design consideration to note for Employee is the multiple different fields that qualify as _keys_, such as an employee id, email address, and phone number. These are fields to guard against duplication. An employee's id is any uniquely generated identifier assigned to it by the company upon joining. Two employees should not share email field or phone number as those two fields are understood to be unique. @@ -226,12 +226,11 @@ The attributes of an Employee are: **Note**: 1. For the commands in this section, the order in which the prefixes (if any) are placed does not matter. - 1. `edit eid/37 a/ntu p/8461 4872` will invoke the same result as `edit eid/37 p/8461 4872 a/ntu` + 1. `edit eid/37 a/ntu p/8461 4872` will return the same result as `edit eid/37 p/8461 4872 a/ntu` 2. If duplicated prefixes are provided, only the argument associated with last instance of the same prefix will be processed by the parser. 3. We make a distinction between the prefixes `id/` and `eid/`. The former is used in commands during adding of an employee or editing of an employee’s Id field whereas the latter is used in commands that references an employee that exists in SudoHR. - #### 4.2.1 Adding an employee The `add` command adds a new employee, with the specified fields, into SudoHR. Note that only the 'Tag' field is optional. @@ -358,6 +357,10 @@ The attributes of a department are: The uniqueness of each department in `UniqueDepartmentList` is enforced by checking against the `DepartmentName`. This will be explained in the _Adding a department_ section. +**Note** +1. For the commands in this section, the order in which the prefixes (if any) are placed does not matter. +2. If duplicated prefixes are provided, only the argument associated with last instance of the same prefix will be processed by the parser. + #### 4.3.1. Adding a department The `adep` command adds a new `Department` in SudoHr. @@ -578,6 +581,10 @@ The attributes of a leave are: - `LeaveDate`: The date of the leave, which is also the unique identifier for a leave - `UniqueEmployeeList` : The employees who applied for this leave, the list must not contain duplicate employees. +**Note** +1. For the commands in this section, the order in which the prefixes (if any) are placed does not matter. +2. If duplicated prefixes are provided, only the argument associated with last instance of the same prefix will be processed by the parser. + #### 4.4.1. Adding an employee's leave The `aetl` command adds an employee's leave on a specific day: @@ -1274,7 +1281,7 @@ testers are expected to do more *exploratory* testing. #### 7.2.3. Editing an employee -1. Test case: `edit eid/1 p/9999999` (employee must exist)
+1. Test case: `edit eid/1 p/99999999` (employee must exist)
Expected: Employee with ID 1 is edited. Details of the edited employee is shown in the result display. 2. Test case: `edit 1 p/88888888` (incorrect format)
Expected: No employee is edited. Result display shows correct command format and command constraints. diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 9b32247a59c..ae27e97466f 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -52,7 +52,7 @@ and 10,000 tags! -------------------------------------------------------------------------------------------------------------------- -# **2. Quick start** +# **2. Quick Start** 1. Ensure you have Java `11` or above installed in your Computer. @@ -67,16 +67,14 @@ and 10,000 tags! 5. Type the command in the command box and press Enter to execute it. e.g. typing **`help`** and pressing Enter will open the help window.
Some example commands you can try: - * `exit` : Exits the app. + * `exit` : Exits the app. + * `help` : Brings up the list of commands for reference 6. Refer to the [Command](#4-commands) below for details of each command. -------------------------------------------------------------------------------------------------------------------- - --------------------------------------------------------------------------------------------------------------------- - # **3. Quick Reference Guide** ## 3.1. Layout @@ -107,7 +105,7 @@ employee. ### 3.1.4 Departments The leftmost panel is the Departments section. Here you can view the status of the departments in your -company. The main data displayed is the number of employees available. +company. The main data displayed is the number of employees in each department. ### 3.1.5 Leaves The last panel on the right is the Leaves section. On this panel, you can view the dates in which employees have @@ -124,8 +122,8 @@ applied for leave. Each leave date would contain the number of employees who app ### 3.2.1. Employee -Employees can be added to SudoHR to better -track their data, involvement in the company, as well as easy retrieval of information. +Employees can be added to SudoHR to better track their data, such as their leaves and the departments that they +belong to, as well as easy retrieval of information. An employee possesses the following attributes: 1. Employee ID @@ -138,7 +136,7 @@ An employee possesses the following attributes: Employees are identified by their IDs. An employee's ID is a unique identification number assigned by the company. So, no two employees should share the same ID. -Similarly, email address and phone number are fields that are not intended for sharing. +Similarly, email address and phone number are fields that belong to a single employee. SudoHR enforces uniqueness for these two fields as well. However, do note that emails are case-sensitive. You cannot add an employee that share any of the following fields with a different employee in SudoHR: @@ -148,7 +146,8 @@ You cannot add an employee that share any of the following fields with a differe ### 3.2.2. Department -A department is made up of a group of employees. A department can have many employees and an employee can be in many departments. +A department is made up of a group of employees. A department can have many employees and an employee can be in many +departments. Every employee in a department must be unique. @@ -179,18 +178,20 @@ There is currently no prefix for **KEYWORD** and **OLD_DEPARTMENT_NAME**. -| Placeholder | Corresponding Prefix | Description| +List placeholders in the command + +| Placeholder | Corresponding Prefix | Description | |-------------------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **ID** | id/ | {::nomarkdown} ID is the unique identifier for an employee. Leading zeroes are ignored.
**Note: This flag is only used when adding an employee into the app**.
It has the following constraints:

Valid Examples: Invalid Examples: {:/} | -| **EMPLOYEE_ID** | eid/ | Similar to ID, The EMPLOYEE_ID represents the ID of an employee.
It is used for any commands that require referencing an employee.
It follows the same constraints as ID. {:/} | -| **NAME** | n/ | {::nomarkdown}NAME represents the name of an employee.
It has the following constraints:

Valid Examples:
  • Kenneth
  • Bob Lim
    • Invalid Examples:
  • Bob*
  • 1Alice
    • {:/} | -| **PHONE_NUMBER** | p/ | {::nomarkdown} PHONE_NUMBER represents the phone number of an employee.
    It has the following constraints:
  • It must contain only 8 digits
  • First 4 digits can be space-separated from the last 4 digits
  • it must be unique

    • Valid Examples:
  • 12345678
  • 9762 8372
    • Invalid Examples:
  • 123
  • Hello
    • {:/} | +| **ID** | id/ | {::nomarkdown} ID is the unique identifier for an employee. Leading zeroes are ignored.
    **Note**: This flag is only used when adding an employee into the app.
    It has the following constraints:

    Valid Examples: Invalid Examples: {:/} | +| **EMPLOYEE_ID** | eid/ | Similar to ID, The EMPLOYEE_ID represents the ID of an employee.
    It is used for any commands that require referencing an employee.
    It follows the same constraints as ID. | +| **NAME** | n/ | {::nomarkdown}NAME represents the name of an employee.
    It has the following constraints:

    Valid Examples:
  • Kenneth
  • Bob Lim
  • Alice1
    • Invalid Examples:
  • Bob*
  • Alice-1
    • {:/} | +| **PHONE_NUMBER** | p/ | {::nomarkdown} PHONE_NUMBER represents the phone number of an employee.
    It has the following constraints:
  • It must contain only 8 digits
  • First 4 digits can be space-separated from the last 4 digits
  • it must be unique

    • Valid Examples:
  • 12345678
  • 9762 8372
    • Invalid Examples:
  • 123
  • Hello
    • {:/} | | **EMAIL** | e/ | {::nomarkdown} EMAIL represents the email address of an employee. It must be of the format local-part@domain
    It has the following constraints:
  • It must be unique
  • The local-part should only contain alphanumeric characters and these special characters, excluding the parentheses, ( +_.- ). The local-part may not start or end with any special characters.
  • This is followed by a '@' and then a domain name. The domain name is made up of domain labels separated by periods.
  • The domain name must:
    1. End with a domain label at least 2 characters long
    2. Have each domain label start and end with alphanumeric characters
    3. Have each domain label consist of alphanumeric characters, separated only by hyphens, if any.
    • Valid Examples:
  • PeterJack+1190@example.com
  • a1+be.d@example1.com
    • Invalid Examples:
  • peter jack@example.com
  • -peterjack@example.com
    • {:/} | -| **ADDRESS** | a/ | {::nomarkdown} ADDRESS represents the home address of an employee.
    It can take on any value! {:/} | +| **ADDRESS** | a/ | {::nomarkdown} ADDRESS represents the home address of an employee.
    It can take on any value! {:/} | | **TAG** | t/ | {::nomarkdown} TAG represents a tag of an employee. This field is optional and is not restrictive in usage.
    For example, it can be used to indicate an employee's position in the department or simple remarks about the employee.
    It has the following constraints:
  • They can only contain alphanumeric characters.

    • Valid Examples:
  • Manager
    • Invalid Examples:
  • *Manager
    • {:/} | -| **DEPARTMENT_NAME** | n/ | {::nomarkdown} DEPARTMENT_NAME is the unique identifier for a department. It is used when creating and deleting a department.
    It has the following constraints:
  • They can only contain alphanumeric characters.

    • Valid Examples:
  • Finance
    • Invalid Examples:
  • *Finance
    • {:/} | -| **OLD_DEPARTMENT_NAME** | NA | {::nomarkdown}OLD_DEPARTMENT_NAME represents the original department name before editing a department. It has the same constraints as DEPARTMENT_NAME.{:/} | -| **NEW_DEPARTMENT_NAME** | n/ | {::nomarkdown}NEW_DEPARTMENT_NAME represents the new department name when editing a department. It has the same constraints as DEPARTMENT_NAME. {:/} | +| **DEPARTMENT_NAME** | n/ | {::nomarkdown} DEPARTMENT_NAME is the unique identifier for a department. It is used when creating and deleting a department.
    It has the following constraints:
  • They can only contain alphanumeric characters and spaces.

    • Valid Examples:
  • Finance
    • Invalid Examples:
  • *Finance
    • {:/} | +| **OLD_DEPARTMENT_NAME** | NA | {::nomarkdown}OLD_DEPARTMENT_NAME represents the original department name before editing a department. It has the same constraints as DEPARTMENT_NAME. {:/} | +| **NEW_DEPARTMENT_NAME** | n/ | {::nomarkdown}NEW_DEPARTMENT_NAME represents the new department name when editing a department. It has the same constraints as DEPARTMENT_NAME. {:/} | | **DATE** | d/ | {::nomarkdown} DATE represents the date of the leave.
    It has the following constraints:
  • The date provided must be of the form YYYY-MM-DD. "YYYY" refers to the year , "MM" refers to the month, and "DD" refers to the day of the month for a specfic day in the calender.
  • The date provided must be a valid calender day.

    • {:/} | | **START_DATE** | s/ | {::nomarkdown} START_DATE represents the start of a range of days where leave is taken.
    It has the following constraints:
  • The date provided must be of the form YYYY-MM-DD. "YYYY" refers to the year , "MM" refers to the month, and "DD" refers to the day of the month for a specfic day in the calender.
  • The date provided must be a valid calender day.

    • {:/} | | **END_DATE** | e/ | {::nomarkdown} START_DATE represents the end of a range of days where leave is taken.
    It has the following constraints:
  • Within a command, the END_DATE cannot be earlier than the START_DATE
  • Within a command, the END_DATE can at most be 6 days later than the START_DATE
  • The date provided must be of the form YYYY-MM-DD. "YYYY" refers to the year , "MM" refers to the month, and "DD" refers to the day of the month for a specfic day in the calender.
  • The date provided must be a valid calender day.

    • {:/} | @@ -211,12 +212,11 @@ It consists of: 2. Prefixes - The identifiers for the various input values, different commands require different prefixes 3. Placeholders - The actual input values for the command. -[//]: # (## 6.4. Trying your first command) - -[//]: # (<-- Insert example context here -->) - - - +
    :exclamation: **NOTE:** +1. For the commands in this section, the order in which the prefixes (if any) are placed does not matter. +2. If duplicated prefixes are provided, only the argument associated with the last instance of the same prefix will + be processed by the parser. +
    -------------------------------------------------------------------------------------------------------------------- # **4. Commands** @@ -447,29 +447,7 @@ Examples: * `leid n/Software Engineering` * `leid n/Sales` -### 4.2.10 List department headcount: `ldhc` - -List all employees present in the given department on a given date. The department window will display only the given -department. -Format: `ldhc n/DEPARTMENT_NAME [d/DATE]` -* If the date is not specified, employees present on the current date of inputting -the command will be shown for the given department. -* The given date must not be before the current date of inputting the command and must be within one year -of the current date of inputting the command. -* The date will be deemed invalid if it does not follow the form YYYY-MM-DD or if the date is not within the range -specified above. - -
    **NOTE:** -The input date must be of the form YYYY-MM-DD -
    - -Examples: -* `ldhc n/Human Resources` -* `ldhc n/Sales d/2023-06-03` - - -![result for 'ldhc n/Sales d/2023-06-03'](images/UiListDepartmentHeadcountCommand.png) ## 4.3. Leave Commands @@ -482,7 +460,7 @@ section. Format: `aetl eid/EMPLOYEE_ID d/DATE`
    **NOTE:** -The employee shouldn't have taken leave on the date provided +The employee should not have taken leave already on the date provided
    **NOTE:** @@ -562,20 +540,40 @@ Examples: ### 4.3.5. Listing all leave dates: `llve` -Displays all leaves taken by employees. +Displays all leaves taken by all employees. Format: `llve` ### 4.3.6. Listing all leaves taken by an employee: `llbe` -Lists all the leave date(s) of an employee. +Lists all the leave date(s) taken by an employee. Format: `llbe eid/EMPLOYEE_ID` Examples: * `llbe eid/1` + +### 4.3.7 List department headcount: `ldhc` + +List all employees present in the given department on a given date. The department window will display only the given +department and the leave window will display only the given date. + +Format: `ldhc n/DEPARTMENT_NAME [d/DATE]` +* If the date is not specified, employees present on the current date of inputting + the command will be shown for the given department. +* The given date must not be before the current date of inputting the command and must be within one year + of the current date of inputting the command. + +Examples: +* `ldhc n/Human Resources` +* `ldhc n/Sales d/2023-06-03` + + +![result for 'ldhc n/Sales d/2023-06-03'](images/UiListDepartmentHeadcountCommand.png) + + ## 4.4. General Commands ### 4.4.1. Viewing help : `help` @@ -658,9 +656,6 @@ If your changes to the data file makes its format invalid, SudoHR will discard a # **5. FAQ** -**Q**: How do I transfer my data to another Computer?
    -**A**: Install the app in the other computer and replace the default empty data file `sudohr.json` with the file that contains the data of your previous SudoHR home folder. - **Q**: There seems to be many commands and prefixes to remember! Is there an easy way to remember them?
    **A**: We understand how the short form command names may be difficult to remember, but don't worry. We have thus created a command summary here in the user guide for you in [section 4.6](#46-command-summary)!
    This list is also available on the app, which can be accessed with the `help` function or by clicking the help tab on the top right corner of the window.