Bug 275106 - Add JavaDoc comments to non-generated Java files. r=darin

git-svn-id: svn://10.0.0.236/trunk@166922 18797224-902f-48f8-a5cc-f745e15eee43

mozilla/extensions/java/xpcom/GeckoEmbed.java

@@ -39,9 +39,44 @@ package org.mozilla.xpcom;
 
 import java.io.*;
 
+/**
+ *  Provides access to functions that are used to embed Mozilla's Gecko layer.
+ */
 public final class GeckoEmbed {
 
-  public static native void initEmbedding(File aMozBinDirectory, AppFileLocProvider aAppFileLocProvider);
-  public static native void termEmbedding();
+  /**
+   * Initializes the Gecko embedding layer. You <i>must</i>
+   * call this method before proceeding to use Gecko. This function ensures
+   * XPCOM is started, creates the component registry if necessary and
+   * starts global services.
+   *
+   * @param aMozBinDirectory The Gecko directory containing the component
+   *                         registry and runtime libraries;
+   *                         or use <code>null</code> to use the working
+   *                         directory.
+   * @param aAppFileLocProvider The object to be used by Gecko that specifies
+   *                         to Gecko where to find profiles, the component
+   *                         registry preferences and so on; or use
+   *                         <code>null</code> for the default behaviour.
+   *
+   * @exception XPCOMException  if a failure occurred during initialization
+   */
+  public static native
+  void initEmbedding(File aMozBinDirectory,
+                     AppFileLocProvider aAppFileLocProvider);
+
+  /**
+   * Terminates the Gecko embedding layer. Call this function during shutdown to
+   * ensure that global services are unloaded, files are closed and
+   * XPCOM is shutdown.
+   * <p>
+   * NOTE: Release any XPCOM objects within Gecko that you may be holding a
+   *       reference to before calling this function.
+   * </p>
+   *
+   * @exception XPCOMException  if a failure occurred during termination
+   */
+  public static native
+  void termEmbedding();
 
 }