Add javadoc

Author: optionsome

application/src/main/java/org/opentripplanner/framework/graphql/GraphQLUtils.java

@@ -7,8 +7,30 @@
 import javax.annotation.Nullable;
 import org.opentripplanner.framework.i18n.I18NString;
 
+/**
+ * This class should always be used when translating fields or handling locales in GraphQL queries.
+ */
 public class GraphQLUtils {
 
+  /**
+   * If input is {@code null}, return null. Otherwise, input is translated using a locale from this
+   * prioritized list:
+   * <ol>
+   *   <li>
+   *   {@code language} parameter of a queried field.
+   *   </li>
+   *   <li>
+   *   Locale from the DataFetchingEnvironment's local context (for journey planning queries this is {@code locale} parameter).
+   *   </li>
+   *   <li>
+   *   DataFetchingEnvironment's locale which comes from the accept-language header.
+   *   </li>
+   *   <li>
+   *   Default locale.
+   *   </li>
+   * </ol>
+   */
+  @Nullable
   public static String getTranslation(
     @Nullable I18NString input,
     DataFetchingEnvironment environment
@@ -19,6 +41,23 @@ public static String getTranslation(
     return input.toString(getLocale(environment));
   }
 
+  /**
+   * Returns locale from this prioritized list:
+   * <ol>
+   *   <li>
+   *   {@code language} parameter of a queried field.
+   *   </li>
+   *   <li>
+   *   Locale from the DataFetchingEnvironment's local context (for journey planning queries this is {@code locale} parameter).
+   *   </li>
+   *   <li>
+   *   DataFetchingEnvironment's locale which comes from the accept-language header.
+   *   </li>
+   *   <li>
+   *   Default locale.
+   *   </li>
+   * </ol>
+   */
   public static Locale getLocale(DataFetchingEnvironment environment) {
     var localeString = environment.getArgument("language");
     if (localeString != null) {
@@ -28,6 +67,23 @@ public static Locale getLocale(DataFetchingEnvironment environment) {
     return getLocaleFromEnvironment(environment);
   }
 
+  /**
+   * Returns locale from this prioritized list:
+   * <ol>
+   *   <li>
+   *   {@code localeString}.
+   *   </li>
+   *   <li>
+   *   Locale from the DataFetchingEnvironment's local context (for journey planning queries this is {@code locale} parameter).
+   *   </li>
+   *   <li>
+   *   DataFetchingEnvironment's locale which comes from the accept-language header.
+   *   </li>
+   *   <li>
+   *   Default locale.
+   *   </li>
+   * </ol>
+   */
   public static Locale getLocale(
     DataFetchingEnvironment environment,
     @Nullable String localeString
@@ -39,6 +95,23 @@ public static Locale getLocale(
     return getLocaleFromEnvironment(environment);
   }
 
+  /**
+   * Returns locale from this prioritized list:
+   * <ol>
+   *   <li>
+   *   {@code locale}.
+   *   </li>
+   *   <li>
+   *   Locale from the DataFetchingEnvironment's local context (for journey planning queries this is {@code locale} parameter).
+   *   </li>
+   *   <li>
+   *   DataFetchingEnvironment's locale which comes from the accept-language header.
+   *   </li>
+   *   <li>
+   *   Default locale.
+   *   </li>
+   * </ol>
+   */
   public static Locale getLocale(DataFetchingEnvironment environment, @Nullable Locale locale) {
     if (locale != null) {
       return locale;
@@ -47,15 +120,33 @@ public static Locale getLocale(DataFetchingEnvironment environment, @Nullable Lo
     return getLocaleFromEnvironment(environment);
   }
 
+  /**
+   * Returns locale from this prioritized list:
+   * <ol>
+   *   <li>
+   *   Locale from the DataFetchingEnvironment's local context (for journey planning queries this is {@code locale} parameter).
+   *   </li>
+   *   <li>
+   *   DataFetchingEnvironment's locale which comes from the accept-language header.
+   *   </li>
+   *   <li>
+   *   Default locale.
+   *   </li>
+   * </ol>
+   */
   public static Locale getLocaleFromEnvironment(DataFetchingEnvironment environment) {
     // This can come from the accept-language header
     var envLocale = environment.getLocale();
     // This can come from a locale param
-    var localContextLocale = getDefaultLocale(environment);
+    var localContextLocale = getLocalContextLocale(environment);
     return localContextLocale.orElse(envLocale);
   }
 
-  private static Optional<Locale> getDefaultLocale(DataFetchingEnvironment environment) {
+  /**
+   * Returns locale from the DataFetchingEnvironment's local context (for journey planning queries
+   * this is {@code locale} parameter) or empty if none exist.
+   */
+  private static Optional<Locale> getLocalContextLocale(DataFetchingEnvironment environment) {
     Map<String, ?> localContext = environment.getLocalContext();
     if (localContext == null) {
       return Optional.empty();