Add some documentation for ShimInterfaceInfo, no bug, DONTBUILD, CLOSED TREE
authorEhsan Akhgari <ehsan@mozilla.com>
Tue, 03 Jun 2014 12:37:08 -0400
changeset 205601 a5a9b382d99049e9be7a71b78150ecdcbce34d0e
parent 205600 6d1c365852197dfaf626ada8ce3334cbe51669f6
child 205602 86b6f32f9c417fc6d606557226d172f561b8141c
push id3741
push userasasaki@mozilla.com
push dateMon, 21 Jul 2014 20:25:18 +0000
treeherdermozilla-beta@4d6f46f5af68 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
milestone32.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Add some documentation for ShimInterfaceInfo, no bug, DONTBUILD, CLOSED TREE
xpcom/reflect/xptinfo/src/ShimInterfaceInfo.cpp
--- a/xpcom/reflect/xptinfo/src/ShimInterfaceInfo.cpp
+++ b/xpcom/reflect/xptinfo/src/ShimInterfaceInfo.cpp
@@ -356,16 +356,50 @@ struct ComponentsInterfaceShimEntry {
 };
 
 #define DEFINE_SHIM_WITH_CUSTOM_INTERFACE(geckoName, domName) \
   { #geckoName, NS_GET_IID(geckoName), \
      mozilla::dom::domName ## Binding::sNativePropertyHooks }
 #define DEFINE_SHIM(name) \
   DEFINE_SHIM_WITH_CUSTOM_INTERFACE(nsIDOM ## name, name)
 
+/**
+ * These shim entries allow us to make old XPIDL interfaces implementing DOM
+ * APIs as non-scriptable in order to save some runtime memory on Firefox OS,
+ * without breaking the entries under Components.interfaces which might both
+ * be used by our code and add-ons.  Specifically, the shim entries provide
+ * the following:
+ *
+ * * Components.interfaces.nsIFoo entries.  These entries basically work
+ *   almost exactly as the usual ones that you would get through the
+ *   XPIDL machinery.  Specifically, they have the right name, they reflect
+ *   the right IID, and they will work properly when passed to QueryInterface.
+ *
+ * * Components.interfaces.nsIFoo.CONSTANT values.  These entries will have
+ *   the right name and the right value for most integer types.  Note that
+ *   support for non-numerical constants is untested and will probably not
+ *   work out of the box.
+ *
+ * FAQ:
+ * * When should I add an entry to the list here?
+ *   Only if you're making an XPIDL interfaces which has a corresponding
+ *   WebIDL interface non-scriptable.
+ * * When should I remove an entry from this list?
+ *   If you are completely removing an XPIDL interface from the code base.  If
+ *   you forget to do so, the compiler will remain you.
+ * * How should I add an entry to the list here?
+ *   First, make sure that the XPIDL interface in question is non-scriptable
+ *   and also has a corresponding WebIDL interface.  Then, add two include
+ *   entries above, one for the XPIDL interface and one for the WebIDL
+ *   interface, and add a shim entry below.  If the name of the XPIDL
+ *   interface only has an "nsIDOM" prefix prepended to the WebIDL name, you
+ *   can use the DEFINE_SHIM macro and pass in the name of the WebIDL
+ *   interface.  Otherwise, use DEFINE_SHIM_WITH_CUSTOM_INTERFACE.
+ */
+
 const ComponentsInterfaceShimEntry kComponentsInterfaceShimMap[] =
 {
   DEFINE_SHIM(AnimationEvent),
   DEFINE_SHIM(Attr),
   DEFINE_SHIM(BeforeUnloadEvent),
   DEFINE_SHIM(CanvasRenderingContext2D),
   DEFINE_SHIM(CDATASection),
   DEFINE_SHIM(CharacterData),