Fix Javadocs broken by google-java-format

Summary: After we ran google-java-format D16071725, some Javadocs which weren't properly written broke. This includes putting unordered and ordered lists not using <ul> and <ol>, putting code blocks and pseudo-graphics not using <pre>. I ran through all the changed classes and tried to fix the broken Javadocs. Reviewed By: cpojer Differential Revision: D16090087 fbshipit-source-id: f31971cbc0e367a04814ff90bbfb2192751d5e16
2025-11-01 09:14:26 +00:00 · 2019-07-02 09:39:21 -07:00
parent 6c0f73b322
commit cd05a85fe5
22 changed files with 271 additions and 112 deletions
@@ -15,12 +15,17 @@ import javax.annotation.Nonnull;

 /**
 * Main interface for providing additional capabilities to the catalyst framework by couple of
- * different means: 1) Registering new native modules 2) Registering new JS modules that may be
- * accessed from native modules or from other parts of the native code (requiring JS modules from
- * the package doesn't mean it will automatically be included as a part of the JS bundle, so there
- * should be a corresponding piece of code on JS side that will require implementation of that JS
- * module so that it gets bundled) 3) Registering custom native views (view managers) and custom
- * event types 4) Registering natively packaged assets/resources (e.g. images) exposed to JS
+ * different means:
+ *
+ * <ol>
+ *   <li>Registering new native modules
+ *   <li>Registering new JS modules that may be accessed from native modules or from other parts of
+ *       the native code (requiring JS modules from the package doesn't mean it will automatically
+ *       be included as a part of the JS bundle, so there should be a corresponding piece of code on
+ *       JS side that will require implementation of that JS module so that it gets bundled)
+ *   <li>Registering custom native views (view managers) and custom event types
+ *   <li>Registering natively packaged assets/resources (e.g. images) exposed to JS
+ * </ol>
 *
 * <p>TODO(6788500, 6788507): Implement support for adding custom views, events and resources
 */
@@ -34,14 +34,19 @@ import javax.annotation.Nullable;
 * operations (such as interpolation, addition, etc) and connection are used to describe how change
 * of the value in one node can affect other nodes.
 *
- * <p>Few examples of the nodes that can be created on the JS side: - Animated.Value is a simplest
- * type of node with a numeric value which can be driven by an animation engine (spring, decay, etc)
- * or by calling setValue on it directly from JS - Animated.add is a type of node that may have two
- * or more input nodes. It outputs the sum of all the input node values - interpolate - is actually
- * a method you can call on any node and it creates a new node that takes the parent node as an
- * input and outputs its interpolated value (e.g. if you have value that can animate from 0 to 1 you
- * can create interpolated node and set output range to be 0 to 100 and when the input node changes
- * the output of interpolated node will multiply the values by 100)
+ * <p>Few examples of the nodes that can be created on the JS side:
+ *
+ * <ul>
+ *   <li>Animated.Value is a simplest type of node with a numeric value which can be driven by an
+ *       animation engine (spring, decay, etc) or by calling setValue on it directly from JS
+ *   <li>Animated.add is a type of node that may have two or more input nodes. It outputs the sum of
+ *       all the input node values
+ *   <li>interpolate - is actually a method you can call on any node and it creates a new node that
+ *       takes the parent node as an input and outputs its interpolated value (e.g. if you have
+ *       value that can animate from 0 to 1 you can create interpolated node and set output range to
+ *       be 0 to 100 and when the input node changes the output of interpolated node will multiply
+ *       the values by 100)
+ * </ul>
 *
 * <p>You can mix and chain nodes however you like and this way create nodes graph with connections
 * between them.
@@ -20,11 +20,16 @@ import javax.annotation.Nullable;
 * occurs.
 *
 * <p>Native methods can be exposed to JS with {@link ReactMethod} annotation. Those methods may
- * only use limited number of types for their arguments: 1/ primitives (boolean, int, float, double
- * 2/ {@link String} mapped from JS string 3/ {@link ReadableArray} mapped from JS Array 4/ {@link
- * ReadableMap} mapped from JS Object 5/ {@link Callback} mapped from js function and can be used
- * only as a last parameter or in the case when it express success & error callback pair as two last
- * arguments respectively.
+ * only use limited number of types for their arguments:
+ *
+ * <ol>
+ *   <li>primitives (boolean, int, float, double
+ *   <li>{@link String} mapped from JS string
+ *   <li>{@link ReadableArray} mapped from JS Array
+ *   <li>{@link ReadableMap} mapped from JS Object
+ *   <li>{@link Callback} mapped from js function and can be used only as a last parameter or in the
+ *       case when it express success & error callback pair as two last arguments respectively.
+ * </ol>
 *
 * <p>All methods exposed as native to JS with {@link ReactMethod} annotation must return {@code
 * void}.
@@ -17,9 +17,13 @@ import javax.annotation.Nullable;
 * app outside of this catalyst instance still in a good state to allow reloading and restarting
 * this catalyst instance?
 *
- * <p>Examples where this class is appropriate to throw: - JS tries to update a view with a tag that
- * hasn't been created yet - JS tries to show a static image that isn't in resources - JS tries to
- * use an unsupported view class
+ * <p>Examples where this class is appropriate to throw:
+ *
+ * <ul>
+ *   <li>JS tries to update a view with a tag that hasn't been created yet
+ *   <li>JS tries to show a static image that isn't in resources
+ *   <li>JS tries to use an unsupported view class
+ * </ul>
 *
 * <p>Examples where this class **isn't** appropriate to throw: - Failed to write to localStorage
 * because disk is full - Assertions about internal state (e.g. that
@@ -12,14 +12,19 @@ package com.facebook.react.bridge;
 * <p>When multiple activities share a react instance, only the most recent one's lifecycle events
 * get forwarded to listeners. Consider the following scenarios:
 *
- * <p>1. Navigating from Activity A to B will trigger two events: A#onHostPause and B#onHostResume.
- * Any subsequent lifecycle events coming from Activity A, such as onHostDestroy, will be ignored.
- * 2. Navigating back from Activity B to Activity A will trigger the same events: B#onHostPause and
- * A#onHostResume. Any subsequent events coming from Activity B, such as onHostDestroy, are ignored.
- * 3. Navigating back from Activity A to a non-React Activity or to the home screen will trigger two
- * events: onHostPause and onHostDestroy. 4. Navigating from Activity A to a non-React Activity B
- * will trigger one event: onHostPause. Later, if Activity A is destroyed (e.g. because of resource
- * contention), onHostDestroy is triggered.
+ * <ol>
+ *   <li>Navigating from Activity A to B will trigger two events: A#onHostPause and B#onHostResume.
+ *       Any subsequent lifecycle events coming from Activity A, such as onHostDestroy, will be
+ *       ignored.
+ *   <li>Navigating back from Activity B to Activity A will trigger the same events: B#onHostPause
+ *       and A#onHostResume. Any subsequent events coming from Activity B, such as onHostDestroy,
+ *       are ignored.
+ *   <li>Navigating back from Activity A to a non-React Activity or to the home screen will trigger
+ *       two events: onHostPause and onHostDestroy.
+ *   <li>Navigating from Activity A to a non-React Activity B will trigger one event: onHostPause.
+ *       Later, if Activity A is destroyed (e.g. because of resource contention), onHostDestroy is
+ *       triggered.
+ * </ol>
 */
 public interface LifecycleEventListener {

@@ -56,9 +56,12 @@ import org.json.JSONObject;
 *
 * <p>One can use 'debug_http_host' shared preferences key to provide a host name for the debug
 * server. If the setting is empty we support and detect two basic configuration that works well for
- * android emulators connection to debug server running on emulator's host: - Android stock emulator
- * with standard non-configurable local loopback alias: 10.0.2.2, - Genymotion emulator with default
- * settings: 10.0.3.2
+ * android emulators connection to debug server running on emulator's host:
+ *
+ * <ul>
+ *   <li>Android stock emulator with standard non-configurable local loopback alias: 10.0.2.2
+ *   <li>Genymotion emulator with default settings: 10.0.3.2
+ * </ul>
 */
 public class DevServerHelper {
  public static final String RELOAD_APP_EXTRA_JS_PROXY = "jsproxy";
@@ -61,12 +61,15 @@ public class DidJSUpdateUiDuringFrameDetector
   * <p>There are two 'success' cases that will cause {@link #getDidJSHitFrameAndCleanup} to return
   * true for a given frame:
   *
-   * <p>1) UIManagerModule finished dispatching a batched UI update on the UI thread during the
-   * frame. This means that during the next hierarchy traversal, new UI will be drawn if needed
-   * (good). 2) The bridge ended the frame idle (meaning there were no JS nor native module calls
-   * still in flight) AND there was no UiManagerModule update enqueued that didn't also finish. NB:
-   * if there was one enqueued that actually finished, we'd have case 1), so effectively we just
-   * look for whether one was enqueued.
+   * <ol>
+   *   <li>UIManagerModule finished dispatching a batched UI update on the UI thread during the
+   *       frame. This means that during the next hierarchy traversal, new UI will be drawn if
+   *       needed (good).
+   *   <li>The bridge ended the frame idle (meaning there were no JS nor native module calls still
+   *       in flight) AND there was no UiManagerModule update enqueued that didn't also finish. NB:
+   *       if there was one enqueued that actually finished, we'd have case 1), so effectively we
+   *       just look for whether one was enqueued.
+   * </ol>
   *
   * <p>NB: This call can only be called once for a given frame time range because it cleans up
   * events it recorded for that frame.
@@ -33,9 +33,12 @@ public class I18nUtil {
  }

  /**
-   * Check if the device is currently running on an RTL locale. This only happens when the app: - is
-   * forcing RTL layout, regardless of the active language (for development purpose) - allows RTL
-   * layout when using RTL locale
+   * Check if the device is currently running on an RTL locale. This only happens when the app:
+   *
+   * <ul>
+   *   <li>is forcing RTL layout, regardless of the active language (for development purpose)
+   *   <li>allows RTL layout when using RTL locale
+   * </ul>
   */
  public boolean isRTL(Context context) {
    if (isRTLForced(context)) {
@@ -40,8 +40,15 @@ import javax.annotation.concurrent.NotThreadSafe;
 /**
 * Delegate of {@link UIManagerModule} that owns the native view hierarchy and mapping between
 * native view names used in JS and corresponding instances of {@link ViewManager}. The {@link
- * UIManagerModule} communicates with this class by it's public interface methods: - {@link
- * #updateProperties} - {@link #updateLayout} - {@link #createView} - {@link #manageChildren}
+ * UIManagerModule} communicates with this class by it's public interface methods:
+ *
+ * <ul>
+ *   <li>{@link #updateProperties}
+ *   <li>{@link #updateLayout}
+ *   <li>{@link #createView}
+ *   <li>{@link #manageChildren}
+ * </ul>
+ *
 * executing all the scheduled UI operations at the end of JS batch.
 *
 * <p>NB: All native view management methods listed above must be called from the UI thread.
@@ -193,8 +193,18 @@ public abstract class ViewManager<T extends View, C extends ReactShadowNode>
   * native views. This should return bubbling directly-dispatched event types and specify what
   * names should be used to subscribe to either form (bubbling/capturing).
   *
-   * <p>Returned map should be of the form: { "onTwirl": { "phasedRegistrationNames": { "bubbled":
-   * "onTwirl", "captured": "onTwirlCaptured" } } }
+   * <p>Returned map should be of the form:
+   *
+   * <pre>
+   * {
+   *   "onTwirl": {
+   *     "phasedRegistrationNames": {
+   *       "bubbled": "onTwirl",
+   *       "captured": "onTwirlCaptured"
+   *     }
+   *   }
+   * }
+   * </pre>
   */
  public @Nullable Map<String, Object> getExportedCustomBubblingEventTypeConstants() {
    return null;
@@ -204,7 +214,15 @@ public abstract class ViewManager<T extends View, C extends ReactShadowNode>
   * Returns a map of config data passed to JS that defines eligible events that can be placed on
   * native views. This should return non-bubbling directly-dispatched event types.
   *
-   * <p>Returned map should be of the form: { "onTwirl": { "registrationName": "onTwirl" } }
+   * <p>Returned map should be of the form:
+   *
+   * <pre>
+   * {
+   *   "onTwirl": {
+   *     "registrationName": "onTwirl"
+   *   }
+   * }
+   * </pre>
   */
  public @Nullable Map<String, Object> getExportedCustomDirectEventTypeConstants() {
    return null;
@@ -20,9 +20,15 @@ import javax.annotation.Nullable;
 * <p>Each annotated method should return {@code void} and take exactly two arguments: first being a
 * view instance to be updated and second a value that should be set.
 *
- * <p>Allowed types of values are: - primitives (int, boolean, double, float) - {@link String} -
- * {@link Boolean} - {@link com.facebook.react.bridge.ReadableArray} - {@link
- * com.facebook.react.bridge.ReadableMap}
+ * <p>Allowed types of values are:
+ *
+ * <ul>
+ *   <li>primitives (int, boolean, double, float)
+ *   <li>{@link String}
+ *   <li>{@link Boolean}
+ *   <li>{@link com.facebook.react.bridge.ReadableArray}
+ *   <li>{@link com.facebook.react.bridge.ReadableMap}
+ * </ul>
 *
 * <p>When property gets removed from the corresponding component in React, annotated setter will be
 * called with {@code null} in case of non-primitive value type or with a default value in case when
@@ -37,13 +37,17 @@ import javax.annotation.Nullable;
 /**
 * ReactModalHostView is a view that sits in the view hierarchy representing a Modal view.
 *
- * <p>It does a number of things: 1. It creates a Dialog. We use this Dialog to actually display the
- * Modal in the window. 2. It creates a DialogRootViewGroup. This view is the view that is displayed
- * by the Dialog. To display a view within a Dialog, that view must have its parent set to the
- * window the Dialog creates. Because of this, we can not use the ReactModalHostView since it sits
- * in the normal React view hierarchy. We do however want all of the layout magic to happen as if
- * the DialogRootViewGroup were part of the hierarchy. Therefore, we forward all view changes around
- * addition and removal of views to the DialogRootViewGroup.
+ * <p>It does a number of things:
+ *
+ * <ol>
+ *   <li>It creates a Dialog. We use this Dialog to actually display the Modal in the window.
+ *   <li>It creates a DialogRootViewGroup. This view is the view that is displayed by the Dialog. To
+ *       display a view within a Dialog, that view must have its parent set to the window the Dialog
+ *       creates. Because of this, we can not use the ReactModalHostView since it sits in the normal
+ *       React view hierarchy. We do however want all of the layout magic to happen as if the
+ *       DialogRootViewGroup were part of the hierarchy. Therefore, we forward all view changes
+ *       around addition and removal of views to the DialogRootViewGroup.
+ * </ol>
 */
 public class ReactModalHostView extends ViewGroup implements LifecycleEventListener {

@@ -351,18 +351,23 @@ public abstract class ReactBaseTextShadowNode extends LayoutShadowNode {
  /**
   * NB: If a font family is used that does not have a style in a certain Android version (ie.
   * monospace bold pre Android 5.0), that style (ie. bold) will not be inherited by nested Text
-   * nodes. To retain that style, you have to add it to those nodes explicitly. Example, Android
-   * 4.4: <Text style={{fontFamily="serif" fontWeight="bold"}}>Bold Text</Text> <Text
-   * style={{fontFamily="sans-serif"}}>Bold Text</Text> <Text style={{fontFamily="serif}}>Bold
-   * Text</Text>
+   * nodes. To retain that style, you have to add it to those nodes explicitly.
   *
-   * <p><Text style={{fontFamily="monospace" fontWeight="bold"}}>Not Bold Text</Text> <Text
-   * style={{fontFamily="sans-serif"}}>Not Bold Text</Text> <Text style={{fontFamily="serif}}>Not
-   * Bold Text</Text>
+   * <p>Example, Android 4.4:
   *
-   * <p><Text style={{fontFamily="monospace" fontWeight="bold"}}>Not Bold Text</Text> <Text
-   * style={{fontFamily="sans-serif" fontWeight="bold"}}>Bold Text</Text> <Text
-   * style={{fontFamily="serif}}>Bold Text</Text>
+   * <pre>
+   * <Text style={{fontFamily="serif" fontWeight="bold"}}>Bold Text</Text>
+   *   <Text style={{fontFamily="sans-serif"}}>Bold Text</Text>
+   *     <Text style={{fontFamily="serif}}>Bold Text</Text>
+   *
+   * <Text style={{fontFamily="monospace" fontWeight="bold"}}>Not Bold Text</Text>
+   *   <Text style={{fontFamily="sans-serif"}}>Not Bold Text</Text>
+   *     <Text style={{fontFamily="serif}}>Not Bold Text</Text>
+   *
+   * <Text style={{fontFamily="monospace" fontWeight="bold"}}>Not Bold Text</Text>
+   *   <Text style={{fontFamily="sans-serif" fontWeight="bold"}}>Bold Text</Text>
+   *     <Text style={{fontFamily="serif}}>Bold Text</Text>
+   * </pre>
   */
  protected @Nullable String mFontFamily = null;

@@ -72,18 +72,23 @@ public class TextAttributeProps {
  /**
   * NB: If a font family is used that does not have a style in a certain Android version (ie.
   * monospace bold pre Android 5.0), that style (ie. bold) will not be inherited by nested Text
-   * nodes. To retain that style, you have to add it to those nodes explicitly. Example, Android
-   * 4.4: <Text style={{fontFamily="serif" fontWeight="bold"}}>Bold Text</Text> <Text
-   * style={{fontFamily="sans-serif"}}>Bold Text</Text> <Text style={{fontFamily="serif}}>Bold
-   * Text</Text>
+   * nodes. To retain that style, you have to add it to those nodes explicitly.
   *
-   * <p><Text style={{fontFamily="monospace" fontWeight="bold"}}>Not Bold Text</Text> <Text
-   * style={{fontFamily="sans-serif"}}>Not Bold Text</Text> <Text style={{fontFamily="serif}}>Not
-   * Bold Text</Text>
+   * <p>Example, Android 4.4:
   *
-   * <p><Text style={{fontFamily="monospace" fontWeight="bold"}}>Not Bold Text</Text> <Text
-   * style={{fontFamily="sans-serif" fontWeight="bold"}}>Bold Text</Text> <Text
-   * style={{fontFamily="serif}}>Bold Text</Text>
+   * <pre>
+   * <Text style={{fontFamily="serif" fontWeight="bold"}}>Bold Text</Text>
+   *   <Text style={{fontFamily="sans-serif"}}>Bold Text</Text>
+   *     <Text style={{fontFamily="serif}}>Bold Text</Text>
+   *
+   * <Text style={{fontFamily="monospace" fontWeight="bold"}}>Not Bold Text</Text>
+   *   <Text style={{fontFamily="sans-serif"}}>Not Bold Text</Text>
+   *     <Text style={{fontFamily="serif}}>Not Bold Text</Text>
+   *
+   * <Text style={{fontFamily="monospace" fontWeight="bold"}}>Not Bold Text</Text>
+   *   <Text style={{fontFamily="sans-serif" fontWeight="bold"}}>Bold Text</Text>
+   *     <Text style={{fontFamily="serif}}>Bold Text</Text>
+   * </pre>
   */
  protected @Nullable String mFontFamily = null;

@@ -15,10 +15,14 @@ import com.facebook.react.uimanager.events.RCTEventEmitter;
 * Event emitted by {@link ReactViewPager} when user scrolls between pages (or when animating
 * between pages).
 *
- * <p>Additional data provided by this event: - position - index of first page from the left that is
- * currently visible - offset - value from range [0,1) describing stage between page transitions.
- * Value x means that (1 - x) fraction of the page at "position" index is visible, and x fraction of
- * the next page is visible.
+ * <p>Additional data provided by this event:
+ *
+ * <ul>
+ *   <li>position - index of first page from the left that is currently visible
+ *   <li>offset - value from range [0,1) describing stage between page transitions. Value x means
+ *       that (1 - x) fraction of the page at "position" index is visible, and x fraction of the
+ *       next page is visible.
+ * </ul>
 */
 /* package */ class PageScrollEvent extends Event<PageScrollEvent> {

@@ -14,7 +14,11 @@ import com.facebook.react.uimanager.events.RCTEventEmitter;
 /**
 * Event emitted by {@link ReactViewPager} when user scrolling state changed.
 *
- * <p>Additional data provided by this event: - pageScrollState - {Idle,Dragging,Settling}
+ * <p>Additional data provided by this event:
+ *
+ * <ul>
+ *   <li>pageScrollState - {Idle,Dragging,Settling}
+ * </ul>
 */
 class PageScrollStateChangedEvent extends Event<PageScrollStateChangedEvent> {

@@ -14,7 +14,11 @@ import com.facebook.react.uimanager.events.RCTEventEmitter;
 /**
 * Event emitted by {@link ReactViewPager} when selected page changes.
 *
- * <p>Additional data provided by this event: - position - index of page that has been selected
+ * <p>Additional data provided by this event:
+ *
+ * <ul>
+ *   <li>position - index of page that has been selected
+ * </ul>
 */
 /* package */ class PageSelectedEvent extends Event<PageSelectedEvent> {