feat: Initial entry for @GtfsValidationNotice annotation (#1361)

* Initial entry for @GtfsValidationNotice annotation, which will be used to configure and document validation notices in source code.

Author: bdferris-v2

main/src/main/java/org/mobilitydata/gtfsvalidator/validator/BlockTripsWithOverlappingStopTimesValidator.java

@@ -1,5 +1,7 @@
 package org.mobilitydata.gtfsvalidator.validator;
 
+import static org.mobilitydata.gtfsvalidator.notice.SeverityLevel.ERROR;
+
 import com.google.common.collect.Multimaps;
 import java.time.LocalDate;
 import java.util.ArrayList;
@@ -8,15 +10,18 @@
 import java.util.List;
 import java.util.Optional;
 import javax.inject.Inject;
+import org.mobilitydata.gtfsvalidator.annotation.GtfsValidationNotice;
+import org.mobilitydata.gtfsvalidator.annotation.GtfsValidationNotice.FileRefs;
+import org.mobilitydata.gtfsvalidator.annotation.GtfsValidationNotice.UrlRef;
 import org.mobilitydata.gtfsvalidator.annotation.GtfsValidator;
 import org.mobilitydata.gtfsvalidator.notice.NoticeContainer;
-import org.mobilitydata.gtfsvalidator.notice.SeverityLevel;
 import org.mobilitydata.gtfsvalidator.notice.ValidationNotice;
 import org.mobilitydata.gtfsvalidator.table.GtfsCalendarDateTableContainer;
 import org.mobilitydata.gtfsvalidator.table.GtfsCalendarTableContainer;
 import org.mobilitydata.gtfsvalidator.table.GtfsStopTime;
 import org.mobilitydata.gtfsvalidator.table.GtfsStopTimeTableContainer;
 import org.mobilitydata.gtfsvalidator.table.GtfsTrip;
+import org.mobilitydata.gtfsvalidator.table.GtfsTripSchema;
 import org.mobilitydata.gtfsvalidator.table.GtfsTripTableContainer;
 import org.mobilitydata.gtfsvalidator.type.GtfsDate;
 import org.mobilitydata.gtfsvalidator.type.GtfsTime;
@@ -259,6 +264,13 @@ public LocalDate getIntersection() {
    *
    * <p>Severity: {@code SeverityLevel.ERROR}
    */
+  @GtfsValidationNotice(
+      severity = ERROR,
+      files = @FileRefs({GtfsTripSchema.class}),
+      urls =
+          @UrlRef(
+              label = "Original Python validator implementation",
+              url = "https://github.com/google/transitfeed"))
   static class BlockTripsWithOverlappingStopTimesNotice extends ValidationNotice {
 
     // The row number from `trips.txt` of the first faulty trip.
@@ -287,7 +299,7 @@ static class BlockTripsWithOverlappingStopTimesNotice extends ValidationNotice {
 
     BlockTripsWithOverlappingStopTimesNotice(
         GtfsTrip tripA, GtfsTrip tripB, GtfsDate intersection) {
-      super(SeverityLevel.ERROR);
+      super(ERROR);
       this.csvRowNumberA = tripA.csvRowNumber();
       this.tripIdA = tripA.tripId();
       this.serviceIdA = tripA.serviceId();

model/src/main/java/org/mobilitydata/gtfsvalidator/annotation/GtfsValidationNotice.java

@@ -0,0 +1,80 @@
+package org.mobilitydata.gtfsvalidator.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import org.mobilitydata.gtfsvalidator.notice.SeverityLevel;
+import org.mobilitydata.gtfsvalidator.table.GtfsEntity;
+
+/**
+ * An annotation used to identify, configure, and document a validation notice. All notices should
+ * be annotated with this type.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface GtfsValidationNotice {
+
+  /**
+   * The default severity level for the notice. The actual severity level may be configured to be
+   * different at validation time.
+   */
+  SeverityLevel severity();
+
+  /**
+   * GTFS specification file references used in automatic documentation generation for the notice.
+   */
+  FileRefs files() default @FileRefs({});
+
+  /**
+   * GTFS Best Practices file references used in automatic documentation generation for the notice.
+   */
+  BestPracticesRefs bestPractices() default @BestPracticesRefs({});
+
+  /**
+   * Arbitrary documentation reference urls used in automatic documentation generation for the
+   * notice.
+   */
+  UrlRef[] urls() default {};
+
+  /**
+   * Annotation used in notice documentation to specify a link to the specification documentation
+   * for a specific GTFS file, as identified by its table schema.
+   */
+  @Retention(RetentionPolicy.RUNTIME)
+  @Target(ElementType.TYPE)
+  @interface BestPracticesRefs {
+    /** The set of GTFS table schemas corresponding to the GTFS file in question. */
+    Class<? extends GtfsEntity>[] value();
+  }
+
+  /**
+   * Annotation used in notice documentation to specify a link to the Best Practices documentation
+   * for a specific GTFS file, as identified by its table schema.
+   */
+  @Retention(RetentionPolicy.RUNTIME)
+  @Target(ElementType.TYPE)
+  @interface FileRefs {
+    /** The set of GTFS table schemas corresponding to the GTFS file in question. */
+    Class<? extends GtfsEntity>[] value();
+
+    /** True if a particular notice applies to all files in the GTFS spec. */
+    boolean allFiles() default false;
+  }
+
+  /**
+   * Annotation used in notice documentation to specify a general reference URL for a notice. For
+   * links to specific GTFS file references and best-practices, use {@link FileRefs} or {@link
+   * BestPracticesRefs} instead.
+   */
+  @Retention(RetentionPolicy.RUNTIME)
+  @Target(ElementType.TYPE)
+  @interface UrlRef {
+
+    /** The human-readable text used to display the url. */
+    String label();
+
+    /** The reference URL. */
+    String url();
+  }
+}