Add/update JavaDoc/comments

Author: cslzchen

src/main/java/io/cos/cas/osf/authentication/support/OsfInstitutionUtils.java

@@ -14,7 +14,7 @@
 import java.util.Map;
 
 /**
- * This is {@link OsfInstitutionUtils}.
+ * This is {@link OsfInstitutionUtils}, which provides helper methods supporting the institution SSO login flow.
  *
  * @author Longze Chen
  * @since 21.0.0
@@ -54,13 +54,16 @@ public static Map<String, String> getInstitutionLoginUrlMap(
         for (final OsfInstitution institution: institutionList) {
             final SsoAvailability ssoAvailability = institution.getSsoAvailability();
             if (ssoAvailability == null) {
+                // Catch a rare exception case where OSF DB has changed the choices of the field
+                // `sso_availability` in table `osf_institution` without syncing with CAS.
                 LOGGER.error(
                         "Skipped due to invalid SSO Availability: [institutionId={}]",
                         institution.getInstitutionId()
                 );
                 continue;
             }
             if (!ssoAvailability.isPublic()) {
+                // Hide institutions of which SSO Availability is not Public
                 LOGGER.debug(
                         "Skipped because SSO Availability is not public: [institutionId={}, ssoAvailability={}]",
                         institution.getInstitutionId(),

src/main/java/io/cos/cas/osf/authentication/support/SsoAvailability.java

@@ -1,7 +1,8 @@
 package io.cos.cas.osf.authentication.support;
 
 /**
- * This is {@link SsoAvailability}.
+ * This is {@link SsoAvailability}, which is used in {@link io.cos.cas.osf.model.OsfInstitution}
+ * to map to the types/choices of its counterpart in the OSF model.
  *
  * @author Longze Chen
  * @since 26.1.0
@@ -40,6 +41,9 @@ public static SsoAvailability getType(final String id) throws IllegalArgumentExc
         throw new IllegalArgumentException("No matching type for id " + id);
     }
 
+    /**
+     * @return whether the enum type is {@link SsoAvailability#PUBLIC}.
+     */
     public boolean isPublic () {
         return SsoAvailability.PUBLIC.equals(this);
     }