docs: improve documentation comments for clarity and consistency across calendar components

Author: kavantrivedi

lib/calendar_view.dart

@@ -2,6 +2,10 @@
 // Use of this source code is governed by a MIT-style license
 // that can be found in the LICENSE file.
 
+/// Calendar widgets, models, themes, and utilities for building day, week,
+/// multi-day, and month calendar UIs in Flutter.
+///
+/// Import this library to access the public API of the package.
 library calendar_view;
 
 export './src/calendar_constants.dart';

lib/src/calendar_event_data.dart

@@ -8,7 +8,7 @@ import '../calendar_view.dart';
 
 @immutable
 
-/// {@macro calendar_event_data_doc}
+/// Stores metadata for a calendar event and its date/time boundaries.
 class CalendarEventData<T extends Object?> {
   /// Specifies date on which all these events are.
   final DateTime date;
@@ -47,7 +47,7 @@ class CalendarEventData<T extends Object?> {
   /// Define reoccurrence settings
   final RecurrenceSettings? recurrenceSettings;
 
-  /// {@macro calendar_event_data_doc}
+  /// Creates an event model used by day, week, multi-day, and month views.
   CalendarEventData({
     required this.title,
     required DateTime date,

lib/src/day_view/day_view.dart

@@ -1012,7 +1012,8 @@ class DayViewState<T extends Object?> extends State<DayView<T>> {
 
   /// Animate to next page (next day).
   ///
-  /// Transitions with animation using [pageTransitionDuration] and [pageTransitionCurve].
+  /// Transitions with animation using [DayView.pageTransitionDuration] and
+  /// [DayView.pageTransitionCurve].
   ///
   /// See also: [previousPage], [jumpToDate], [animateToDate]
   void nextPage({Duration? duration, Curve? curve}) => _pageController.nextPage(
@@ -1022,7 +1023,8 @@ class DayViewState<T extends Object?> extends State<DayView<T>> {
 
   /// Animate to previous page (previous day).
   ///
-  /// Transitions with animation using [pageTransitionDuration] and [pageTransitionCurve].
+  /// Transitions with animation using [DayView.pageTransitionDuration] and
+  /// [DayView.pageTransitionCurve].
   ///
   /// See also: [nextPage], [jumpToDate], [animateToDate]
   void previousPage({Duration? duration, Curve? curve}) =>
@@ -1056,20 +1058,21 @@ class DayViewState<T extends Object?> extends State<DayView<T>> {
           duration: duration ?? widget.pageTransitionDuration,
           curve: curve ?? widget.pageTransitionCurve);
 
-  /// Returns current page index (number of days since [minDay]).
+  /// Returns current page index (number of days since [DayView.minDay]).
   int get currentPage => _currentIndex;
 
   /// Jumps to page which gives day calendar for [date]
   ///
   /// This is the preferred way to navigate to a specific date. It automatically
-  /// calculates the correct page index based on the [minDay] parameter.
+  /// calculates the correct page index based on [DayView.minDay].
   ///
   /// **Example:**
   /// ```dart
   /// dayViewState.jumpToDate(DateTime(2024, 5, 15));
   /// ```
   ///
-  /// **Note:** The [date] must be within the range [minDay] to [maxDay],
+  /// **Note:** The [date] must be within the range [DayView.minDay] to
+  /// [DayView.maxDay],
   /// otherwise an exception will be thrown.
   ///
   /// Throws an exception if [date] is outside the valid date range.
@@ -1082,10 +1085,12 @@ class DayViewState<T extends Object?> extends State<DayView<T>> {
 
   /// Animate to page which gives day calendar for [date].
   ///
-  /// Calculates the correct page index based on [minDay] and animates to it.
+  /// Calculates the correct page index based on [DayView.minDay] and animates
+  /// to it.
   /// Arguments [duration] and [curve] override default transition values.
   ///
-  /// Throws an exception if [date] is outside the [minDay] to [maxDay] range.
+  /// Throws an exception if [date] is outside the [DayView.minDay] to
+  /// [DayView.maxDay] range.
   Future<void> animateToDate(DateTime date,
       {Duration? duration, Curve? curve}) async {
     if (date.isBefore(_minDate) || date.isAfter(_maxDate)) {

lib/src/event_arrangers/event_arrangers.dart

@@ -26,7 +26,7 @@ abstract class EventArranger<T extends Object?> {
   ///
   /// There are three predefined class that implements of [EventArranger].
   ///
-  /// [_StackEventArranger], [SideEventArranger] and [MergeEventArranger].
+  /// [SideEventArranger], and [MergeEventArranger].
   ///
   const EventArranger();
 

lib/src/event_controller.dart

@@ -117,7 +117,7 @@ class EventController<T extends Object?> extends ChangeNotifier {
     notifyListeners();
   }
 
-  /// Adds a single event in [_events]
+  /// Adds a single event to this controller.
   void add(CalendarEventData<T> event) {
     _calendarData.addEvent(event);
     notifyListeners();

lib/src/extensions.dart

@@ -69,7 +69,7 @@ extension DateTimeExtensions on DateTime {
   ///
   /// ex: if Current Date instance is 8th and day is wednesday then weekDates
   /// will return dates
-  /// [6,7,8,9,10,11,12]
+  /// 6, 7, 8, 9, 10, 11, 12.
   /// Where on 6th there will be monday and on 12th there will be Sunday
   List<DateTime> datesOfWeek({
     WeekDays start = WeekDays.monday,

lib/src/modals.dart

@@ -147,7 +147,7 @@ class LiveTimeIndicatorSettings {
 ///
 /// [startDate]: Defines start date of repeating events.
 /// [endDate]: Defines end date of repeating events.
-/// [occurrence]: Defines repetition of an event for the given number of
+/// [occurrences]: Defines repetition of an event for the given number of
 /// occurrences.
 ///
 /// [frequency]: Defines mode of repetition like repeat daily, weekly, monthly

lib/src/month_view/month_view.dart

@@ -738,7 +738,8 @@ class MonthViewState<T extends Object?> extends State<MonthView<T>> {
     );
   }
 
-  /// Returns current page index (number of months since [minMonth]).
+  /// Returns current page index (number of months since
+  /// [MonthViewStyle.minMonth]).
   ///
   /// Use [currentDate] to get the current month as a DateTime.
   ///

lib/src/month_view/month_view_builders.dart

@@ -70,7 +70,7 @@ class MonthViewBuilders<T extends Object?> {
 
   /// This function will generate WeekDayString in weekday view.
   /// Useful for I18n
-  /// Ex : ['Mon','Tue','Wed','Thu','Fri','Sat','Sun']
+  /// Example: Mon, Tue, Wed, Thu, Fri, Sat, Sun.
   final String Function(int)? weekDayStringBuilder;
 
   /// Called when user changes month.

lib/src/month_view/month_view_style.dart

@@ -71,11 +71,11 @@ class MonthViewStyle {
   final Color? borderColor;
 
   /// Page transition duration used when user try to change page using
-  /// [MonthView.nextPage] or [MonthView.previousPage]
+  /// [MonthViewState.nextPage] or [MonthViewState.previousPage].
   final Duration pageTransitionDuration;
 
   /// Page transition curve used when user try to change page using
-  /// [MonthView.nextPage] or [MonthView.previousPage]
+  /// [MonthViewState.nextPage] or [MonthViewState.previousPage].
   final Curve pageTransitionCurve;
 
   /// Defines width of default border