feat: Add Notice documentation header check. (#1422)

* Add notice documentation header check.

* Fix typo.

core/src/main/java/org/mobilitydata/gtfsvalidator/notice/schema/NoticeSchemaGenerator.java

@@ -104,7 +104,7 @@ static NoticeSchema generateSchemaForNotice(Class<? extends Notice> noticeClass)
     return schema;
   }
 
-  private static NoticeDocComments loadComments(Class<?> noticeClass) {
+  public static NoticeDocComments loadComments(Class<?> noticeClass) {
     String resourceName = NoticeDocComments.getResourceNameForClass(noticeClass);
     InputStream is = noticeClass.getResourceAsStream(resourceName);
     if (is == null) {

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

@@ -66,6 +66,12 @@ public void validate(NoticeContainer noticeContainer) {
     }
   }
 
+  /**
+   * Dataset should not contain date ranges for services that have already expired.
+   *
+   * <p>This warning takes into account the `calendar_dates.txt` file as well as the `calendar.txt`
+   * file.
+   */
   @GtfsValidationNotice(
       severity = WARNING,
       urls = {

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

@@ -78,6 +78,10 @@ public void validate(GtfsFeedInfo entity, NoticeContainer noticeContainer) {
     }
   }
 
+  /**
+   * The dataset expiration date defined in `feed_info.txt` is in seven days or less. At any time,
+   * the published GTFS dataset should be valid for at least the next 7 days.
+   */
   @GtfsValidationNotice(severity = WARNING)
   static class FeedExpirationDate7DaysNotice extends ValidationNotice {
 
@@ -106,6 +110,10 @@ static class FeedExpirationDate7DaysNotice extends ValidationNotice {
     }
   }
 
+  /**
+   * At any time, the GTFS dataset should cover at least the next 30 days of service, and ideally
+   * for as long as the operator is confident that the schedule will continue to be operated.
+   */
   @GtfsValidationNotice(
       severity = WARNING,
       urls = {

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

@@ -39,6 +39,7 @@ public void validate(GtfsPathway pathway, NoticeContainer noticeContainer) {
     }
   }
 
+  /** A pathway should not have same values for `from_stop_id` and `to_stop_id`. */
   @GtfsValidationNotice(severity = WARNING, files = @FileRefs(GtfsPathwaySchema.class))
   static class PathwayLoopNotice extends ValidationNotice {
 

main/src/test/java/org/mobilitydata/gtfsvalidator/validator/NoticeDocumentationTest.java

@@ -1,11 +1,13 @@
 package org.mobilitydata.gtfsvalidator.validator;
 
 import static com.google.common.truth.Truth.assertThat;
+import static com.google.common.truth.Truth.assertWithMessage;
 
 import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.InputStreamReader;
+import java.util.List;
 import java.util.Optional;
 import java.util.Set;
 import java.util.regex.Matcher;
@@ -16,6 +18,8 @@
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
 import org.mobilitydata.gtfsvalidator.notice.Notice;
+import org.mobilitydata.gtfsvalidator.notice.NoticeDocComments;
+import org.mobilitydata.gtfsvalidator.notice.schema.NoticeSchemaGenerator;
 
 @RunWith(JUnit4.class)
 public class NoticeDocumentationTest {
@@ -51,6 +55,22 @@ public void testThatRulesMarkdownContainsHeadersForAllValidationNotices() throws
     assertThat(fromMarkdown).isEqualTo(fromSource);
   }
 
+  @Test
+  public void testThatAllValidationNoticesAreDocumented() {
+    List<Class<?>> noticesWithoutDocComment =
+        discoverValidationNoticeClasses()
+            .filter(
+                clazz -> {
+                  NoticeDocComments docComments = NoticeSchemaGenerator.loadComments(clazz);
+                  return docComments.getDocComment() == null;
+                })
+            .collect(Collectors.toList());
+    assertWithMessage(
+            "We expect all validation notices to have a documentation comment.  If this test fails, it likely means that a Javadoc /** */ documentation header needs to be added to the following classes:")
+        .that(noticesWithoutDocComment)
+        .isEmpty();
+  }
+
   private static Stream<Class<Notice>> discoverValidationNoticeClasses() {
     return ClassGraphDiscovery.discoverNoticeSubclasses(ClassGraphDiscovery.DEFAULT_NOTICE_PACKAGES)
         .stream();