From aea5266da5792534e275b913c932c213d8fe6e5c Mon Sep 17 00:00:00 2001 From: Zihlu Wang Date: Sun, 6 Aug 2023 21:05:11 +0800 Subject: [PATCH] docs(webcal): Optimised javadoc --- .../org/codecrafters/webcal/WebCalendar.java | 113 +++++---- .../codecrafters/webcal/WebCalendarEvent.java | 125 ++++++---- .../codecrafters/webcal/WebCalendarNode.java | 229 +++--------------- .../webcal/config/Classification.java | 54 ++++- .../webcal/config/package-info.java | 34 +++ .../org/codecrafters/webcal/package-info.java | 44 ++++ 6 files changed, 297 insertions(+), 302 deletions(-) create mode 100644 webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java create mode 100644 webcal/src/main/java/cn/org/codecrafters/webcal/package-info.java diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendar.java b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendar.java index c96e64a..f36603f 100644 --- a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendar.java +++ b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendar.java @@ -21,71 +21,74 @@ import java.util.ArrayList; import java.util.List; /** - * WebCalendar + * The WebCalendar class represents a web calendar in iCalendar format. + * + *

+ * It allows users to create and customize calendar components and events and + * generate an iCalendar string containing all the calendar information. + * + *

Usage Example: + * 

+ * WebCalendar calendar = new WebCalendar()
+ *         .setName("My Web Calendar")
+ *         .setCompanyName("CodeCrafters Inc.")
+ *         .setProductName("WebCal")
+ *         .setDomainName("codecrafters.org.cn")
+ *         .setMethod("PUBLISH")
+ *         .addEvent(event1)
+ *         .addEvent(event2);
+ * String iCalendarString = calendar.resolve();
+ *
+ * + *

+ * The WebCalendar class is designed to generate an iCalendar string conforming + * to the iCalendar specification, which can be used to share calendar data + * with other calendar applications or services. * * @author Zihlu Wang + * @version 1.0.0 + * @since 1.0.0 */ public final class WebCalendar { - // - // Constants - // - - // Tag + /** + * The VCALENDAR tag for iCalendar format + */ private final static String TAG = "VCALENDAR"; - // - // Fields - // - + // Calendar properties private String name; - /** - * Company name. This value is to specify the {@code productIdentifier} - * property. - */ private String companyName; - /** - * Product name. This value is to specify the {@code productIdentifier} - * property. - */ private String productName; private String domainName; - /** - * Calendar scale, referenced from RFC 5545 - 3.7.1. Calendar Scale. - */ private final String scale = "GREGORIAN"; - /** - * Method, referenced from RFC 5545 - 3.7.2. Method. - */ private String method; private final String version = "2.0"; - private List nodes; + /** + * List of calendar components and events + */ + private final List nodes; - // - // Constructors - // + /** + * Constructor for WebCalendar class, initializes the list of calendar + * components and events. + */ public WebCalendar() { this.nodes = new ArrayList<>(); } - // - // Methods - // - /** - * Set the name for this calendar. + * Set the name of the web calendar. * - * @param name The name for the calendar. - * @return The calendar instance. + * @param name the name of the web calendar + * @return the WebCalendar object */ public WebCalendar setName(String name) { this.name = name; @@ -93,26 +96,32 @@ public final class WebCalendar { } /** - * Set the company name for this calendar. + * Set the company name associated with the web calendar. * - * @param companyName The company name for the calendar. - * @return The calendar instance. + * @param companyName the company name + * @return the WebCalendar object */ public WebCalendar setCompanyName(String companyName) { this.companyName = companyName; return this; } + /** + * Set the domain name associated with the web calendar. + * + * @param domainName the domain name + * @return the WebCalendar object + */ public WebCalendar setDomainName(String domainName) { this.domainName = domainName; return this; } /** - * Set the product name for this calendar. + * Set the product name of the web calendar. * - * @param productName The product name for the calendar. - * @return The calendar instance. + * @param productName the product name + * @return the WebCalendar object */ public WebCalendar setProductName(String productName) { this.productName = productName; @@ -120,10 +129,10 @@ public final class WebCalendar { } /** - * Set the method for this calendar. + * Set the method for publishing the web calendar. * - * @param method The product name for the calendar. - * @return The calendar instance. + * @param method the publishing method + * @return the WebCalendar object */ public WebCalendar setMethod(String method) { this.method = method; @@ -131,10 +140,10 @@ public final class WebCalendar { } /** - * Add a calendar node to this calendar. + * Add an event to the web calendar. * - * @param node Any calendar node. - * @return The calendar instance. + * @param node the calendar component or event to be added + * @return the WebCalendar object */ public WebCalendar addEvent(WebCalendarNode node) { this.nodes.add(node); @@ -142,13 +151,13 @@ public final class WebCalendar { } /** - * Resolve the calendar instance to a text that implements RFC-5545. + * Generate and resolve the iCalendar string for the web calendar. * - * @return A string includes all events in this calendar. + * @return the resolved iCalendar string */ public String resolve() { var events = new StringBuilder(); - if (nodes != null && !nodes.isEmpty()) { + if (!nodes.isEmpty()) { nodes.forEach(item -> events.append(item.setDomainName(domainName) .resolve())); diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java index 0c94f0a..598a32f 100644 --- a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java +++ b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java @@ -28,19 +28,31 @@ import java.util.Optional; import java.util.UUID; /** - * WebCalendarEvent + * The WebCalendarEvent class represents an event in the web calendar. It + * extends the abstract class WebCalendarNode and provides additional methods + * to set properties specific to events. + * + *

+ * Users can use the methods in this class to add categories, set the + * classification, add comments, descriptions, locations, set percent complete + * , set priority, set summary, set start time, set end time, set duration, set + * URL, set UID, and set timezone for the event. After setting the properties, + * users can call the {@link #resolve()} method to generate the corresponding + * iCalendar content for the event. * * @author Zihlu Wang + * @version 1.0.0 + * @since 1.0.0 */ public final class WebCalendarEvent extends WebCalendarNode { private final static String TAG = "VEVENT"; /** - * Add a batch of categories. + * Add categories to the event. * - * @param categories A batch of categories. - * @return The Event instance. + * @param categories the categories to add + * @return the WebCalendarEvent object */ public WebCalendarEvent addCategories(String... categories) { this.categories.addAll(Arrays.asList(categories)); @@ -48,10 +60,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Add a batch of categories. + * Add a collection of categories to the event. * - * @param categories A batch of categories. - * @return The Event instance. + * @param categories the collection of categories to add + * @return the WebCalendarEvent object */ public WebCalendarEvent addCategories(Collection categories) { this.categories.addAll(categories); @@ -59,10 +71,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Add a category. + * Add a single category to the event. * - * @param category A category. - * @return The Event instance. + * @param category the category to add + * @return the WebCalendarEvent object */ public WebCalendarEvent addCategory(String category) { this.categories.add(category); @@ -70,10 +82,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the classification. + * Set the classification of the event. * - * @param classification The specified classification value. - * @return The Event instance. + * @param classification the classification to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setClassification(Classification classification) { this.classification = classification; @@ -81,10 +93,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the comment. + * Set the comment for the event. * - * @param comment The comment. - * @return The Event instance. + * @param comment the comment to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setComment(String comment) { this.comment = comment; @@ -92,10 +104,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the description. + * Set the description for the event. * - * @param description The description. - * @return The Event instance. + * @param description the description to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setDescription(String description) { this.description = description; @@ -103,10 +115,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the location. + * Set the location for the event. * - * @param location The location. - * @return The Event instance. + * @param location the location to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setLocation(String location) { this.location = location; @@ -114,10 +126,11 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the percent complete value. + * Set the percent complete for the event. * - * @param percentComplete The percent complete value. - * @return The Event instance. + * @param percentComplete the percent complete to set + * @return the WebCalendarEvent object + * @throws IllegalArgumentException if the percent complete is out of range (0 ~ 100) */ public WebCalendarEvent setPercentComplete(Integer percentComplete) { if (percentComplete < 0 || percentComplete > 100) { @@ -128,10 +141,11 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set a priority. + * Set the priority for the event. * - * @param priority The priority to be set. - * @return The Event instance. + * @param priority the priority to set + * @return the WebCalendarEvent object + * @throws IllegalArgumentException if the priority is out of range (0 ~ 9) */ public WebCalendarEvent setPriority(Integer priority) { if (priority < 0 || priority > 9) { @@ -142,10 +156,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the summary. + * Set the summary for the event. * - * @param summary The summary (you can also call it as a title). - * @return The Event instance. + * @param summary the summary to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setSummary(String summary) { this.summary = summary; @@ -153,10 +167,11 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the end of this node. + * Set the end time for the event. * - * @param end The end time of this event. - * @return The Event instance. + * @param end the end time to set + * @return the WebCalendarEvent object + * @throws IllegalStateException if the field DURATION has been set before */ public WebCalendarEvent setEnd(LocalDateTime end) { if (this.duration != null) { @@ -167,10 +182,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the start of this event. + * Set the start time for the event. * - * @param start The date time specify the start time of this event. - * @return The Event instance. + * @param start the start time to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setStart(LocalDateTime start) { this.start = start; @@ -178,10 +193,11 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the duration of this event. + * Set the duration for the event. * - * @param duration The duration of this event. - * @return The Event instance. + * @param duration the duration to set + * @return the WebCalendarEvent object + * @throws IllegalStateException if the field END has been set before */ public WebCalendarEvent setDuration(Duration duration) { if (this.end != null) { @@ -192,10 +208,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the URL. + * Set the URL for the event. * - * @param url The URL. - * @return The Event instance. + * @param url the URL to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setUrl(String url) { this.url = url; @@ -203,10 +219,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the uid of this event. + * Set the UID for the event. * - * @param uid The uid. - * @return The Event instance. + * @param uid the UID to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setUid(String uid) { this.uid = uid; @@ -214,10 +230,10 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the domain name of this event. + * Set the domain name for the event. * - * @param domainName The domain name. - * @return The Event instance. + * @param domainName the domain name to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setDomainName(String domainName) { this.domainName = domainName; @@ -225,16 +241,21 @@ public final class WebCalendarEvent extends WebCalendarNode { } /** - * Set the timezone of this event. + * Set the timezone for the event. * - * @param timezone The time zone to set. - * @return The Event instance. + * @param timezone the timezone to set + * @return the WebCalendarEvent object */ public WebCalendarEvent setTimezone(String timezone) { this.timezone = timezone; return this; } + /** + * Generate and resolve the iCalendar content for the event. + * + * @return the resolved iCalendar content for the event + */ @Override public String resolve() { return "\nBEGIN:" + TAG + "\n" + diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java index a1090cf..dba99b6 100644 --- a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java +++ b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java @@ -25,220 +25,45 @@ import java.util.ArrayList; import java.util.List; /** - * WebCalendarNode + * The abstract sealed class WebCalendarNode represents a node in the web + * calendar, such as an event, a to-do item, or an alarm. It provides common + * properties and methods for all calendar components and events. + * + *

+ * Subclasses of WebCalendarNode should implement the {@link #resolve()} method + * to generate the corresponding iCalendar content for the specific calendar + * component or event. * * @author Zihlu Wang + * @version 1.0.0 + * @since 1.0.0 */ public abstract sealed class WebCalendarNode permits WebCalendarEvent { - /** - *

- * Categories, is used to specify categories or subtypes of the calendar component. The categories are useful in - * searching for a calendar component of a particular type and category. - *

- * - * Template: - * 
CATEGORIES:APPOINTMENT,EDUCATION
- * 
CATEGORIES:MEETING
- * - *

Referenced from RFC-5545 - 3.8.1.2. Categories

- */ + // Common properties for all calendar components and events protected List categories; - /** - *

- * Classification, An access classification is only one component of the general security system within a calendar - * application. It provides a method of capturing the scope of the access the calendar owner intends for information - * within an individual calendar entry. - *

- * - * Template: - * 
CLASS:protected
- * - *

Referenced from RFC-5545 - 3.8.1.3. Classification

- */ protected Classification classification; - /** - *

- * Comment, is used to specify a comment to the calendar user. - *

- * - * Template: - * 
-     * COMMENT:The meeting really needs to include both ourselves
-     * and the customer. We can't hold this meeting without them.
-     * As a matter of fact\, the venue for the meeting ought to be at
-     * their site. - - John
-     *
- * - *

Referenced from RFC-5545 - 3.8.1.4. Comment

- */ protected String comment; - /** - *

- * Description is used in the {@link WebCalendarEvent} and to-do to capture lengthy extual descriptions associated with - * the activity. - *

- *

- * Description is used in the Journal calendar component to capture one or more textual journal entries. - *

- *

- * Description is used in the Alarm calendar component to capture the display text for a DISPLAY category of - * alarm, and to capture the body text for an EMAIL category of alarm. - *

- * - * Template: - * 
-     * DESCRIPTION:Meeting to provide technical review for "Phoenix"
-     * design.\nHappy Face Conference Room. Phoenix design team
-     * MUST attend this meeting.\nRSVP to team leader.
-     *
- * - *

Referenced from RFC-5545 - 3.8.1.5. Description

- */ protected String description; - - - /** - *

- * Location, Specific venues such as conference or meeting rooms may be explicitly specified using this property. - *

- * - *

- * Note
- * This location has not implement the URI of the location. - *

- * - * Template: - * 
LOCATION:Conference Room - F123\, Bldg. 002
- * 
LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":
-     *      Conference Room - F123\, Bldg. 002
- * - *

Referenced from RFC-5545 - 3.8.1.7. Location

- */ protected String location; - - - /** - *

- * Percent Complete, is a positive integer between 0 and 100. A value of "0" indicates the to-do has not yet been - * started. A value of "100" indicates that the to-do has been completed. Integer values in between indicate the - * percent partially complete. - *

- * - * Template: - * 
PERCENT-COMPLETE:39
- * - *

Referenced from RFC-5545 - 3.8.1.8. Percent Complete

- */ protected Integer percentComplete; - - - /** - *

- * Priority, is specified as an integer in the range 0 to 9. A value of 0 specifies an undefined priority. A value - * of 1 is the highest priority. A value of 2 is the second-highest priority. Subsequent numbers specify a - * decreasing ordinal priority. A value of 9 is the lowest priority. - *

- * - * Example: - * - */ protected Integer priority; - - - /** - *

- * Summary, is used to capture a short, one-line summary about the activity or journal entry. - *

- * - * Example: - * 
SUMMARY:Department Party
- */ protected String summary; - - - // /** - // * Completed defines the date and time that a to-do was actually completed. - // * - // *

- // * Example: - // * 

COMPLETED:19960401T150000Z
- // *

- // */ - // protected DateTime completed; - // - // /** - // * Set the specific time of the completion of this to-do event. - // * - // * @param completed The complete time. - // */ - // protected void setCompleted(DateTime completed) { - // this.completed = completed; - // } - - /** - * End defines the date and time by which the event ends. - * - * Example: - * 
DTEND:19960401T150000Z
- * 
DTEND;VALUE=DATE:19980704
- */ protected LocalDateTime end; - - - /** - * Start defines the start date and time for the event. - * - * Example: - * 
DTSTART:19980118T073000Z
- * 
DTSTART;VALUE=DATE:19980118
- */ protected LocalDateTime start; - - - /** - * Duration may be used to specify a duration of the event, instead of an explicit end DATE-TIME. - * - * Example: - * 
DURATION:PT100000S
- */ protected Duration duration; - - - /** - * URL may be used in a calendar component to convey a location where a more dynamic rendition of the calendar - * information associated with the calendar component can be found. - * - * Example: - * 
URL:http://example.com/pub/calendars/jsmith/mytime.ics
- */ protected String url; protected String uid; @@ -247,23 +72,30 @@ public abstract sealed class WebCalendarNode protected String timezone; - - - // - // Constructors - // + /** + * Constructor for WebCalendarNode class, initializes the list of + * categories associated with the calendar component or event. + */ protected WebCalendarNode() { this.categories = new ArrayList<>(); } + /** + * Set the domain name associated with the calendar component or event. + * + * @param domainName the domain name + * @return the WebCalendarNode object + */ public WebCalendarNode setDomainName(String domainName) { this.domainName = domainName; return this; } - // - // Protected methods - // + /** + * Resolve the list of categories into a comma-separated string. + * + * @return the comma-separated string of categories + */ protected String resolveCategories() { var builder = new StringBuilder(); if (categories != null && !categories.isEmpty()) { @@ -273,9 +105,12 @@ public abstract sealed class WebCalendarNode return builder.toString(); } - // - // Abstract methods - // + /** + * Generate and resolve the iCalendar content for the calendar component or + * event. + * + * @return the resolved iCalendar content + */ public abstract String resolve(); } diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java b/webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java index 94a5588..102a0c1 100644 --- a/webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java +++ b/webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java @@ -18,25 +18,77 @@ package cn.org.codecrafters.webcal.config; /** - * WebCalClassification + * The Classification enum represents the classification levels of calendar + * content based on RFC 5545. + * + *

+ * Calendar events or components can be classified as one of the following + * levels: + *

* * @author Zihlu Wang + * @version 1.0.0 + * @since 1.0.0 */ public enum Classification { + /** + * Public classification level. + * + *

+ * Indicates that the calendar content is public and can be freely + * distributed. + */ PUBLIC("PUBLIC"), + /** + * Private classification level. + * + *

+ * Indicates that the calendar content is private and should not be shared + * with others. + */ PRIVATE("PRIVATE"), + /** + * Confidential classification level. + * + *

+ * Indicates that the calendar content is confidential and should be kept + * strictly private. + */ CONFIDENTIAL("CONFIDENTIAL"), ; private final String classification; + /** + * Constructor for Classification enum. + * + * @param classification the classification level as a string representation + */ Classification(String classification) { this.classification = classification; } + /** + * Get the string representation of the classification level. + * + * @return the string representation of the classification level + */ public String getClassification() { return classification; } diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java b/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java new file mode 100644 index 0000000..894709e --- /dev/null +++ b/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java @@ -0,0 +1,34 @@ +/* + * Copyright (C) 2023 CodeCraftersCN. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * The package cn.org.codecrafters.webcal.config contains classes related to + * the configuration and settings of the web calendar module. It provides + * various configurations and constants used in the generation and resolution + * of iCalendar content. + * + *

The classes in this package include:

+ * + * + * @since 1.0.0 + */ +package cn.org.codecrafters.webcal.config; \ No newline at end of file diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/package-info.java b/webcal/src/main/java/cn/org/codecrafters/webcal/package-info.java new file mode 100644 index 0000000..0091201 --- /dev/null +++ b/webcal/src/main/java/cn/org/codecrafters/webcal/package-info.java @@ -0,0 +1,44 @@ +/* + * Copyright (C) 2023 CodeCraftersCN. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * The package {@code cn.org.codecrafters.webcal} contains classes and modules + * related to web calendar generation and resolution. It provides functionality + * to create and manage iCalendar content for web-based calendar applications. + * + *

+ * The main classes and modules in this package include: + *

+ * + * @since 1.0.0 + */ +package cn.org.codecrafters.webcal; \ No newline at end of file