Merge 9709df6 into 68432a4

docs/AboutUs.adoc

@@ -38,7 +38,7 @@ image::sharan8.png[width="150", align="left"]
 {empty}[https://github.com/sharan8[github]] [<<sharan8#, portfolio>>]
 
 Role: Developer +
-Responsibilities: Statistics Feature
+Responsibilities: Certificate Export Feature
 
 '''
 

docs/DeveloperGuide.adoc

@@ -526,21 +526,29 @@ This is only possible when in the 'volunteer' context. The information included
 * Date of export
 * Volunteer name
 * Volunteer ID
-* List of events involved in - Event name, hours contributed, event start and event end dates
+* List of events involved in - Event name, event ID, hours contributed, event start and event end dates
+* Total hours contributed across all events
 
 Currently, the certificate will be exported to either of these two locations:
 
-* Folder named 'Certs' in the user's current working directory (next to jar file)
-* Direct to Desktop (if permission not allowed for the above)
+* Folder named 'Certs' in the user's current working directory
+* Direct to the user's current working directory (next to the .jar file)
 
-This is what the exported PDF certificate currently looks like:
+This is what the exported PDF certificate will look like:
 
-.Current form of exported volunteer certificate
+.Sample exported volunteer certificate
 [.thumb]
-image::CurrentVolunteerCert.png[width="600"]
+image::CurrentVolunteerCert.png[width="500"]
 
+// tag::exportcert-sharan-ppp[]
 ===== Implementation
 
+The following activity diagram shows us the control flow of the `exportcert` feature. Analysing this diagram would be a good way to understand the intended functionality of this feature.
+
+.`exportcert` command activity diagram
+[.thumb]
+image::command_exportcert_ad.png[width="500"]
+
 The following steps were involved in this feature's implementation:
 
 1. Support for accepting `exportcert` command.
@@ -561,10 +569,20 @@ The following steps were involved in this feature's implementation:
 * Retrieve the event IDs from the relevant filtered records, along with the hours contributed.
 * Get the Event that corresponds to the event ID, and retrieve its name, startDate and endDate for input into the certificate.
 
-5. Use Apache PDFBox to create and export a volunteer certificate with the information retrieved.
+5. Use of Apache PDFBox to create and export a volunteer certificate with the information retrieved.
 * Involves the creation of a new https://pdfbox.apache.org/docs/2.0.2/javadocs/index.html?org/apache/pdfbox/pdmodel/PDDocument.html[PDDocument],
 with a https://pdfbox.apache.org/docs/2.0.2/javadocs/org/apache/pdfbox/pdmodel/PDPage.html[PDPage] to write the content to.
-* A https://pdfbox.apache.org/docs/2.0.2/javadocs/org/apache/pdfbox/pdmodel/PDPageContentStream.html[PDPageContentStream] is then used to write the information to a page content stream.
+* Writing of the information to a page content stream is then achieved using https://pdfbox.apache.org/docs/2.0.2/javadocs/org/apache/pdfbox/pdmodel/PDPageContentStream.html[PDPageContentStream].
+
+The following sequence diagrams show how the `exportcert` operation will be executed for a valid command `exportcert 1`. Analyse these diagrams to achieve a more detailed understanding of the internal interactions involved in the execution of this feature.
+
+.Sequence diagram for `exportcert 1` with simplified ExportCertCommand execution
+image::command_exportcert_sd_1.png[exportcert SD, 800]
+
+The next sequence diagram below looks at the ExportCertCommand's execution in detail, including it's interaction with the model.
+
+.Detailed sequence diagram for ExportCertCommand execution
+image::command_exportcert_sd_2.png[exportcert SD, 650]
 
 ===== Design Considerations
 
@@ -619,44 +637,74 @@ with a https://pdfbox.apache.org/docs/2.0.2/javadocs/org/apache/pdfbox/pdmodel/P
 +
 
 
-====== Aspect: Choice of additional details for identifying volunteer from certificate
+====== Aspect: Choice of export location
 
-* **Alternative 1 (current choice):** Use Volunteer's NRIC
+* **Alternative 1 (current choice):** Export to the user's current working directory
 +
 [cols="1,10"]
 |===
-|*Pros*| Is unique to each volunteer and can be recovered easily, given the volunteer's name or other personal information. It also adds credibility to the exported volunteer certificate.
-|*Cons*| Requires more space as each NRIC can be represented as string of length 9 or a 7-digit integer.
+|*Pros*| Putting the files relative to where the app is allows the user to locate, manage and access the exports easily as this is a portable app. The app jar and the exported files can be shifted to different locations together easily as well.
+|*Cons*| Navigating to this directory would be necessary if he/she wishes to access the files independent of using the application.
 |===
 +
 
-* **Alternative 2:** Use a Volunteer ID
+* **Alternative 2:** Export to the user's Desktop
 +
 [cols="1,10"]
 |===
-|*Pros*| Shorter than NRIC and still serves the purpose, and can be auto-incremented.
-|*Cons*| Hard to recover, even if additional information about the volunteer is provided. Would also be meaningless to a third person to whom the certificate is presented for verification purposes.
+|*Pros*| Easy to access files when not using the application.
+|*Cons*| As it is a portable app, it may be cumbersome to keep navigating to the Desktop to access the exports when using the application. It also becomes harder to move the app jar and exports together from place to place.
 |===
 +
 
+* **Alternative 3:** Allow the user to specify the export filepath as an argument
++
+[cols="1,10"]
+|===
+|*Pros*| Allows for greater customisability, thus catering to each user's unique needs.
+|*Cons*| Requires user to have accurate prior knowledge of the machine's filepath format. Moreover, support for all possible OS filepath formats within the application may not be possible as well (e.g. custom OS filepath).
+|===
++
 
-====== Aspect: Choice of export location
 
-* **Alternative 1 (current choice):** Create a folder in the user's current working directory
+====== Aspect: Organisation of PDF generation code
+
+* **Alternative 1 (current choice):** Encapsulate within a `CertGenerator` class with exposed public method(s)
 +
 [cols="1,10"]
 |===
-|*Pros*| Putting the files relative to where the app is allows the user to locate, manage and access the exports easily as this is a portable app. The app jar and the exported files can be shifted to different locations together easily as well.
-|*Cons*| The user would have to navigate to this directory if he/she wishes to access the files independent of using the application.
+|*Pros*| Allows for separation of concerns as handling command result or exceptions & retrieving volunteer data is separated from the creation, population and export of the certificate. Also allows for future extension of the PDF generation feature (e.g. generating event reports) through adding a `ExportPdf` abstract class or interface with `generatePdf`, `populatePdf` and `exportPdf` methods to be implemented.
+|*Cons*| Introduces inherent coupling between `ExportCertCommand` and `CertGenerator` classes as currently, only `ExportCertCommand` includes the certificate generation functionality.
 |===
 +
 
-* **Alternative 2 (also part of current choice, if no permission for 1):** Export to the user's Desktop
+* **Alternative 2:** Leave PDF generation code inside a method within the `ExportCertCommand` class
 +
 [cols="1,10"]
 |===
-|*Pros*| Easy to access files when not using the application.
-|*Cons*| As it is a portable app, it may be cumbersome to keep navigating to the Desktop to access the exports when using the application. It also becomes harder to move the app jar and exports together from place to place.
+|*Pros*| Allows the certificate generation code to reside exactly where it is used, as the certificate generation functionality is currently only used by `ExportCertCommand`.
+|*Cons*| Causes a low level of cohesion by packaging different functionalities within `ExportCertCommand`. The functionality to export PDFs also remains unabstracted, and thus extending the functionality to create e.g. event report PDFs would require repetition of the PDF generation code.
+|===
++
+// end::exportcert-sharan-ppp[]
+
+====== Aspect: Choice of additional details for identifying volunteer from certificate
+
+* **Alternative 1 (current choice):** Use Volunteer's NRIC
++
+[cols="1,10"]
+|===
+|*Pros*| Adds credibility to the certificate by displaying something that is unique to each volunteer, and can be recovered easily given the volunteer's name or other personal information.
+|*Cons*| Requires more space as each NRIC has to be represented as string of length 9 or a 7-digit integer.
+|===
++
+
+* **Alternative 2:** Use a Volunteer ID
++
+[cols="1,10"]
+|===
+|*Pros*| Achieves the intended purpose (additional volunteer identification), while encompassing the ability to be auto-incremented.
+|*Cons*| Hard to recover, even if additional information about the volunteer is provided. It would also be meaningless to a third person to whom the certificate is presented for verification purposes.
 |===
 +
 
@@ -1716,8 +1764,6 @@ These instructions only provide a starting point for testers to work on; testers
 .. Re-launch the app by double-clicking the jar file. +
    Expected: The most recent window size and location is retained.
 
-_{ more test cases ... }_
-
 === Deleting a volunteer
 
 . Deleting a volunteer while all persons are listed
@@ -1729,13 +1775,3 @@ _{ more test cases ... }_
    Expected: No volunteer is deleted. Error details shown in the status message. Status bar remains the same.
 .. Other incorrect delete commands to try: `delete`, `delete x` (where x is larger than the list size) _{give more}_ +
    Expected: Similar to previous.
-
-_{ more test cases ... }_
-
-=== Saving data
-
-. Dealing with missing/corrupted data files
-
-.. _{explain how to simulate a missing/corrupted file and the expected behavior}_
-
-_{ more test cases ... }_

docs/UserGuide.adoc

@@ -373,6 +373,7 @@ image::command_volunteer_delete_after.png[After delete, 200]
 --
 
 // tag::exportcert[]
+// tag::exportcert-sharan-ppp[]
 [[command-volunteer-exportcert]]
 ==== Exporting volunteer certificate : `exportcert`
 
@@ -382,7 +383,8 @@ Exports a PDF document to the user's current working directory detailing a volun
 * Date of export
 * Volunteer name
 * Volunteer NRIC
-* List of events involved in - Event name, hours contributed, event start date and event end date
+* List of events involved in - Event name, event ID, hours contributed, event start date and event end date
+* Total hours contributed across all events
 
 Format: `exportcert VOLUNTEER_INDEX`
 
@@ -408,18 +410,25 @@ A success message will also be displayed in the following form: 'Certificate exp
 If SocialCare has the permission to create folders on your machine, the certificates will be exported to a folder named 'Certs'. Else, they can be found next to the .jar file used to run the application.
 ====
 
-Here is what the exported certificate will look like:
+Here is what the exported certificate will look like: (Note that the number within the square brackets [ ] following the event name corresponds to the event ID)
 
 .Sample exported volunteer certificate
 [.thumb]
-image::CurrentVolunteerCert.png[width="600"]
+image::CurrentVolunteerCert.png[width="450"]
 
 An empty line is provided at the end of the certificate for manual signing off. Feel free to add a signature or an organizational stamp to add credibility to the certificate!
 
 [NOTE]
 ====
 To avoid exported file name clashes for volunteers with the same name, we have appended the volunteer's NRIC to the filename as well. Exported file names will have the format '<VOLUNTEER NAME>_<VOLUNTEER NRIC>.pdf' (E.g. John Doe_S8512345A.pdf)
 ====
+// end::exportcert-sharan-ppp[]
+
+You can refer to the following flowchart to better understand the feedback messages displayed by the application, and derive what your subsequent actions should be. (E.g. If you get the message "The volunteer index provided is invalid.", then try replacing the <INDEX> you had input.)
+
+.`exportcert` command flowchart
+[.thumb]
+image::command_exportcert_ad.png[width="500"]
 // end::exportcert[]
 
 // tag::eventmanagement[]

docs/team/sharan8.adoc

@@ -9,12 +9,12 @@
 ---
 
 == Overview
-This project portfolio page serves to document my contributions to _SocialCare_, a software engineering project that was
+This project portfolio page serves to document my contributions to _SocialCare_, a *software engineering project* that was
 undertaken as part of the National University of Singapore (NUS) School of Computing's beginner Software Engineering
 module, CS2103T. More information on this module can be found
 https://nus-cs2103-ay1819s1.github.io/cs2103-website/admin/index.html[here].
 
-_SocialCare_ is an *event and volunteer management system* for social welfare organisations, which runs on desktops.
+_SocialCare_ is an *event and volunteer management system* for administrators of social welfare organisations, which runs on desktops.
 The user interacts with it using the Command Line Interface (CLI), and it has a Graphical User Interface (GUI)
 created using https://docs.oracle.com/javafx/2/overview/jfxpub-overview.htm[JavaFX]. The application is written in Java,
 and has about 10,000 lines of code.
@@ -32,14 +32,15 @@ mouse/GUI driven application.
 
 == Summary of contributions
 
+This section summarizes my contributions to this project and to my fellow course mates throughout the course of the module. It includes enhancements made and a link to the code that I contributed as well.
+
 * *Major enhancement*: I added *the ability to export volunteer certificates in PDF format.*
 ** _What it does_: This feature allows the user to export a volunteer’s event records and contributed hours in the form
 of a PDF certificate.
-** _Justification_: This feature improves the product significantly as it automates a task that is currently done
-largely manually, and offers the user a way to access information from outside of the application as well (via portable
+** _Justification_: This feature improves the product significantly as it automates a task that is currently done manually by referencing files of volunteer records and painstakingly entering information into a word document. It also offers the user a way to access information from outside of the application as well (via portable
 and printable PDF files).
 ** _Highlights_: This enhancement involved an in-depth analysis of available external open source libraries, and
-meticulous design of the exported PDF document.
+meticulous design of the PDF document to be exported.
 ** _Credits_: This feature was developed with the use of https://pdfbox.apache.org/team.html[Apache PDFBox], which
 provides the functionality to create and write to PDF files.
 
@@ -59,8 +60,7 @@ https://github.com/CS2103-AY1819S1-W16-2/main/blob/master/docs/DeveloperGuide.ad
 *** Reviewed PRs (with non-trivial review comments): {pullURL}/92[#92], {pullURL}/107[#107], {pullURL}/114[#114], {pullURL}/232[#232]
 *** Involved forum members in the resolution of a design consideration: https://github.com/nus-cs2103-AY1819S1/forum/issues/114[#114]
 *** Shared a personal learning point with forum members: https://github.com/nus-cs2103-AY1819S1/forum/issues/143[#143]
-*** Reported bugs and suggestions for other teams: To be updated.
-*** Some parts of the `exportcert` feature I added inspired the implementation of the import/export csv/xml feature.
+*** Provided inspiration for the implementation of the import/export csv/xml feature, specifically through my handling of file export to main and backup filepaths in the `exportcert` feature I added.
 ** Tools:
 *** Integrated a third party library (https://pdfbox.apache.org/index.html[Apache PDFBox]) to the project
 ({pullURL}/161[#161]).
@@ -69,22 +69,23 @@ https://github.com/CS2103-AY1819S1-W16-2/main/blob/master/docs/DeveloperGuide.ad
 https://docs.google.com/document/d/19iV64xK0EwaV8kjMaP72P1G7iGKKXtEX2my5M-QowKc/edit?usp=sharing[Brainstorming Canvas]
 to brainstorm on product morphing ideas using the 'Target User Profile-Problem-Value Proposition' framework.
 *** Conceptualised and validated the idea for _SocialCare_ through conversing with staff from 2
-social welfare organisations that I have worked with in the past.
+social welfare organisations that I have worked with in the past, who are part of our intended target group.
+*** Contacted a software engineer from the industry to find out how Extreme Programming is actually employed, and shared the takeaways with my group and classmates.
 
 == Contributions to the User Guide
 
 |===
-|_Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting
+|_Given below is the section I contributed to the User Guide pertaining to the feature that I implemented, `exportcert`. It showcases my ability to write and design documentation targeting
 end-users._
 |===
 
-include::../UserGuide.adoc[tag=exportcert]
+include::../UserGuide.adoc[tag=exportcert-sharan-ppp]
 
 == Contributions to the Developer Guide
 
 |===
-|_Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical
-documentation and the technical depth of my contributions to the project._
+|_Given below is an excerpt from the section I contributed to the Developer Guide. It showcases my ability to write technical
+documentation which showcases the technical depth of my contributions to the project, along with my ability to critically analyse design considerations._
 |===
 
-include::../DeveloperGuide.adoc[tag=exportcert]
+include::../DeveloperGuide.adoc[tag=exportcert-sharan-ppp]