Bug 1291458 - Update documentation for nsILoadInfo. r=tanvi
authorChristoph Kerschbaumer <ckerschb@christophkerschbaumer.com>
Tue, 20 Sep 2016 08:34:40 +0200
changeset 314445 008c6f3dc23937d9c5883a088b2ba5afe249c908
parent 314444 f9fc3453e993dfc805593074b59827880bf26ffe
child 314446 5f268206cfe7456db23cb68160737878333c5edc
push id81896
push usermozilla@christophkerschbaumer.com
push dateTue, 20 Sep 2016 07:01:19 +0000
treeherdermozilla-inbound@a3056e9ae41a [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerstanvi
bugs1291458
milestone52.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
Bug 1291458 - Update documentation for nsILoadInfo. r=tanvi
netwerk/base/NetUtil.jsm
netwerk/base/nsIChannel.idl
netwerk/base/nsIIOService.idl
netwerk/base/nsIIOService2.idl
netwerk/base/nsILoadInfo.idl
netwerk/base/nsNetUtil.h
netwerk/protocol/websocket/nsIWebSocketChannel.idl
--- a/netwerk/base/NetUtil.jsm
+++ b/netwerk/base/NetUtil.jsm
@@ -219,73 +219,27 @@ this.NetUtil = {
      *        {
      *          uri:
      *            The full URI spec string, nsIURI or nsIFile to create the
      *            channel for.
      *            Note that this cannot be an nsIFile if you have to specify a
      *            non-default charset or base URI.  Call NetUtil.newURI first if
      *            you need to construct an URI using those options.
      *          loadingNode:
-     *            The loadingDocument of the channel.
-     *            The element or document where the result of this request will
-     *            be used.  This is the document/element that will get access to
-     *            the result of this request.  For example for an image load,
-     *            it's the document in which the image will be loaded.  And for
-     *            a CSS stylesheet it's the document whose rendering will be
-     *            affected by the stylesheet.
-     *            If possible, pass in the element which is performing the load.
-     *            But if the load is coming from a JS API (such as
-     *            XMLHttpRequest) or if the load might be coalesced across
-     *            multiple elements (such as for <img>) then pass in the
-     *            Document node instead.
-     *            For loads that are not related to any document, such as loads
-     *            coming from addons or internal browser features, omit this
-     *            property and specify a loadingPrincipal or
-     *            loadUsingSystemPrincipal instead.
      *          loadingPrincipal:
-     *            The loadingPrincipal of the channel.
-     *            The principal of the document where the result of this request
-     *            will be used.
-     *            This defaults to the principal of aLoadingNode, so when
-     *            aLoadingNode is passed this can be left as null. However for
-     *            loads where aLoadingNode is null this argument must be passed.
-     *            For example for loads from a WebWorker, pass the principal of
-     *            that worker.  For loads from an addon or from internal browser
-     *            features, pass the system principal.
-     *            This principal should almost always be the system principal if
-     *            loadingNode is omitted, in which case you can use the
-     *            useSystemPrincipal property.  The only exception to this is
-     *            for loads from WebWorkers since they don't have any nodes to
-     *            be passed as loadingNode.
-     *            Please note, loadingPrincipal is *not* the principal of the
-     *            resource being loaded, but rather the principal of the context
-     *            where the resource will be used.
+     *          triggeringPrincipal:
+     *          securityFlags:
+     *          contentPolicyType:
+     *            These will be used as values for the nsILoadInfo object on the
+     *            created channel. For details, see nsILoadInfo in nsILoadInfo.idl
      *          loadUsingSystemPrincipal:
      *            Set this to true to use the system principal as
      *            loadingPrincipal.  This must be omitted if loadingPrincipal or
      *            loadingNode are present.
      *            This should be used with care as it skips security checks.
-     *          triggeringPrincipal:
-     *            The triggeringPrincipal of the load.
-     *            The triggeringPrincipal is the principal of the resource that
-     *            caused this particular URL to be loaded.
-     *            Most likely the triggeringPrincipal and the loadingPrincipal
-     *            are identical, in which case the triggeringPrincipal can be
-     *            left out.  In some cases the loadingPrincipal and the
-     *            triggeringPrincipal are different however, e.g. a stylesheet
-     *            may import a subresource.  In that case the principal of the
-     *            stylesheet which contains the import command is the
-     *            triggeringPrincipal, and the principal of the document whose
-     *            rendering is affected is the loadingPrincipal.
-     *          securityFlags:
-     *            The securityFlags of the channel.
-     *            Any of the securityflags defined in nsILoadInfo.idl.
-     *          contentPolicyType:
-     *            The contentPolicyType of the channel.
-     *            Any of the content types defined in nsIContentPolicy.idl.
      *        }
      * @param aOriginCharset [deprecated]
      *        The character set for the URI.  Only used if aWhatToLoad is a
      *        string, which is a deprecated API.  Must be undefined otherwise.
      *        Use NetUtil.newURI if you need to use this option.
      * @param aBaseURI [deprecated]
      *        The base URI for the spec.  Only used if aWhatToLoad is a string,
      *        which is a deprecated API.  Must be undefined otherwise.  Use
--- a/netwerk/base/nsIChannel.idl
+++ b/netwerk/base/nsIChannel.idl
@@ -329,19 +329,23 @@ interface nsIChannel : nsIRequest
      * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
      * doesn't exist for this type of channel or is empty.
      *
      * @deprecated Use contentDisposition/contentDispositionFilename instead.
      */
     readonly attribute ACString contentDispositionHeader;
 
     /**
-     * The nsILoadInfo for this load.  This is immutable for the
-     * lifetime of the load and should be passed through across
-     * redirects and the like.
+     * The LoadInfo object contains information about a network load, why it
+     * was started, and how we plan on using the resulting response.
+     * If a network request is redirected, the new channel will receive a new
+     * LoadInfo object. The new object will contain mostly the same
+     * information as the pre-redirect one, but updated as appropriate.
+     * For detailed information about what parts of LoadInfo are updated on
+     * redirect, see documentation on individual properties.
      */
     attribute nsILoadInfo loadInfo;
 
 %{ C++
   inline already_AddRefed<nsILoadInfo> GetLoadInfo()
   {
     nsCOMPtr<nsILoadInfo> result;
     mozilla::DebugOnly<nsresult> rv = GetLoadInfo(getter_AddRefs(result));
--- a/netwerk/base/nsIIOService.idl
+++ b/netwerk/base/nsIIOService.idl
@@ -66,63 +66,22 @@ interface nsIIOService : nsISupports
     nsIURI newFileURI(in nsIFile aFile);
 
     /**
      * Creates a channel for a given URI.
      *
      * @param aURI
      *        nsIURI from which to make a channel
      * @param aLoadingNode
-     *        The loadingDocument of the channel.
-     *        The element or document where the result of this request will be
-     *        used. This is the document/element that will get access to the
-     *        result of this request. For example for an image load, it's the
-     *        document in which the image will be loaded. And for a CSS
-     *        stylesheet it's the document whose rendering will be affected by
-     *        the stylesheet.
-     *        If possible, pass in the element which is performing the load. But
-     *        if the load is coming from a JS API (such as XMLHttpRequest) or if
-     *        the load might be coalesced across multiple elements (such as
-     *        for <img>) then pass in the Document node instead.
-     *        For loads that are not related to any document, such as loads coming
-     *        from addons or internal browser features, use null here.
      * @param aLoadingPrincipal
-     *        The loadingPrincipal of the channel.
-     *        The principal of the document where the result of this request will
-     *        be used.
-     *        This defaults to the principal of aLoadingNode, so when aLoadingNode
-     *        is passed this can be left as null. However for loads where
-     *        aLoadingNode is null this argument must be passed.
-     *        For example for loads from a WebWorker, pass the principal
-     *        of that worker. For loads from an addon or from internal browser
-     *        features, pass the system principal.
-     *        This principal should almost always be the system principal if
-     *        aLoadingNode is null. The only exception to this is for loads
-     *        from WebWorkers since they don't have any nodes to be passed as
-     *        aLoadingNode.
-     *        Please note, aLoadingPrincipal is *not* the principal of the
-     *        resource being loaded. But rather the principal of the context
-     *        where the resource will be used.
      * @param aTriggeringPrincipal
-     *        The triggeringPrincipal of the load.
-     *        The triggeringPrincipal is the principal of the resource that caused
-     *        this particular URL to be loaded.
-     *        Most likely the triggeringPrincipal and the loadingPrincipal are
-     *        identical, in which case the triggeringPrincipal can be left out.
-     *        In some cases the loadingPrincipal and the triggeringPrincipal are
-     *        different however, e.g. a stylesheet may import a subresource. In
-     *        that case the principal of the stylesheet which contains the
-     *        import command is the triggeringPrincipal, and the principal of
-     *        the document whose rendering is affected is the loadingPrincipal.
      * @param aSecurityFlags
-     *        The securityFlags of the channel.
-     *        Any of the securityflags defined in nsILoadInfo.idl
      * @param aContentPolicyType
-     *        The contentPolicyType of the channel.
-     *        Any of the content types defined in nsIContentPolicy.idl
+     *        These will be used as values for the nsILoadInfo object on the
+     *        created channel. For details, see nsILoadInfo in nsILoadInfo.idl
      * @return reference to the new nsIChannel object
      *
      * Please note, if you provide both a loadingNode and a loadingPrincipal,
      * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
      * But less error prone is to just supply a loadingNode.
      *
      * Keep in mind that URIs coming from a webpage should *never* use the
      * systemPrincipal as the loadingPrincipal.
--- a/netwerk/base/nsIIOService2.idl
+++ b/netwerk/base/nsIIOService2.idl
@@ -36,63 +36,22 @@ interface nsIIOService2 : nsIIOService
    * @param aURI
    *        nsIURI from which to make a channel
    * @param aProxyURI
    *        nsIURI to use for proxy resolution. Can be null in which
    *        case aURI is used
    * @param aProxyFlags flags from nsIProtocolProxyService to use
    *        when resolving proxies for this new channel
    * @param aLoadingNode
-   *        The loadingDocument of the channel.
-   *        The element or document where the result of this request will be
-   *        used. This is the document/element that will get access to the
-   *        result of this request. For example for an image load, it's the
-   *        document in which the image will be loaded. And for a CSS
-   *        stylesheet it's the document whose rendering will be affected by
-   *        the stylesheet.
-   *        If possible, pass in the element which is performing the load. But
-   *        if the load is coming from a JS API (such as XMLHttpRequest) or if
-   *        the load might be coalesced across multiple elements (such as
-   *        for <img>) then pass in the Document node instead.
-   *        For loads that are not related to any document, such as loads coming
-   *        from addons or internal browser features, use null here.
    * @param aLoadingPrincipal
-   *        The loadingPrincipal of the channel.
-   *        The principal of the document where the result of this request will
-   *        be used.
-   *        This defaults to the principal of aLoadingNode, so when aLoadingNode
-   *        is passed this can be left as null. However for loads where
-   *        aLoadingNode is null this argument must be passed.
-   *        For example for loads from a WebWorker, pass the principal
-   *        of that worker. For loads from an addon or from internal browser
-   *        features, pass the system principal.
-   *        This principal should almost always be the system principal if
-   *        aLoadingNode is null. The only exception to this is for loads
-   *        from WebWorkers since they don't have any nodes to be passed as
-   *        aLoadingNode.
-   *        Please note, aLoadingPrincipal is *not* the principal of the
-   *        resource being loaded. But rather the principal of the context
-   *        where the resource will be used.
    * @param aTriggeringPrincipal
-   *        The triggeringPrincipal of the load.
-   *        The triggeringPrincipal is the principal of the resource that caused
-   *        this particular URL to be loaded.
-   *        Most likely the triggeringPrincipal and the loadingPrincipal are
-   *        identical, in which case the triggeringPrincipal can be left out.
-   *        In some cases the loadingPrincipal and the triggeringPrincipal are
-   *        different however, e.g. a stylesheet may import a subresource. In
-   *        that case the principal of the stylesheet which contains the
-   *        import command is the triggeringPrincipal, and the principal of
-   *        the document whose rendering is affected is the loadingPrincipal.
    * @param aSecurityFlags
-   *        The securityFlags of the channel.
-   *        Any of the securityflags defined in nsILoadInfo.idl
    * @param aContentPolicyType
-   *        The contentPolicyType of the channel.
-   *        Any of the content types defined in nsIContentPolicy.idl
+   *        These will be used as values for the nsILoadInfo object on the
+   *        created channel. For details, see nsILoadInfo in nsILoadInfo.idl
    * @return reference to the new nsIChannel object
    *
    * Please note, if you provide both a loadingNode and a loadingPrincipal,
    * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
    * But less error prone is to just supply a loadingNode.
    */
   nsIChannel newChannelFromURIWithProxyFlags2(in nsIURI aURI,
                                               in nsIURI aProxyURI,
--- a/netwerk/base/nsILoadInfo.idl
+++ b/netwerk/base/nsILoadInfo.idl
@@ -22,17 +22,23 @@ class nsCString;
 [ref] native const_nsIPrincipalArray(const nsTArray<nsCOMPtr<nsIPrincipal>>);
 native NeckoOriginAttributes(mozilla::NeckoOriginAttributes);
 [ref] native const_OriginAttributesRef(const mozilla::NeckoOriginAttributes);
 [ref] native StringArrayRef(const nsTArray<nsCString>);
 
 typedef unsigned long nsSecurityFlags;
 
 /**
- * An nsILoadOwner represents per-load information about who started the load.
+ * The LoadInfo object contains information about a network load, why it
+ * was started, and how we plan on using the resulting response.
+ * If a network request is redirected, the new channel will receive a new
+ * LoadInfo object. The new object will contain mostly the same
+ * information as the pre-redirect one, but updated as appropriate.
+ * For detailed information about what parts of LoadInfo are updated on
+ * redirect, see documentation on individual properties.
  */
 [scriptable, builtinclass, uuid(ddc65bf9-2f60-41ab-b22a-4f1ae9efcd36)]
 interface nsILoadInfo : nsISupports
 {
   /**
    * *** DEPRECATED ***
    * No LoadInfo created within Gecko should contain this security flag.
    * Please use any of the five security flags defined underneath.
@@ -179,79 +185,102 @@ interface nsILoadInfo : nsISupports
 
   /**
    * Load an error page, it should be one of following : about:neterror,
    * about:certerror, about:blocked, or about:tabcrashed.
    */
   const unsigned long SEC_LOAD_ERROR_PAGE = (1<<14);
 
   /**
-   * The loadingPrincipal is the principal that is responsible for the load.
-   * It is *NOT* the principal tied to the resource/URI that this
-   * channel is loading, it's the principal of the resource's
-   * caller or requester. For example, if this channel is loading
-   * an image from http://b.com that is embedded in a document
-   * who's origin is http://a.com, the loadingPrincipal is http://a.com.
+   * This is the principal of the network request's caller/requester where
+   * the resulting resource will be used. I.e. it is the principal which
+   * will get access to the result of the request. (Where "get access to"
+   * might simply mean "embed" depending on the type of resource that is
+   * loaded).
    *
-   * The loadingPrincipal will never be null.
+   * For example for an image, it is the principal of the document where
+   * the image is rendered. For a stylesheet it is the principal of the
+   * document where the stylesheet will be applied.
+   *
+   * So if document at http://a.com/page.html loads an image from
+   * http://b.com/pic.jpg, then loadingPrincipal will be
+   * http://a.com/page.html.
+   *
+   * For <iframe> and <frame> loads, the LoadingPrincipal is the
+   * principal of the parent document. For top-level loads, the
+   * LoadingPrincipal is null. For all loads except top-level loads
+   * the LoadingPrincipal is never null.
    */
   readonly attribute nsIPrincipal loadingPrincipal;
 
   /**
    * A C++-friendly version of loadingPrincipal.
    */
   [noscript, notxpcom, nostdcall, binaryname(LoadingPrincipal)]
   nsIPrincipal binaryLoadingPrincipal();
 
   /**
-   * The triggeringPrincipal is the principal that triggerd the load.
-   * Most likely the triggeringPrincipal and the loadingPrincipal are the same,
-   * in which case triggeringPrincipal returns the loadingPrincipal.
-   * In some cases the loadingPrincipal and the triggeringPrincipal are different
-   * however, e.g. a stylesheet may import a subresource. In that case the
-   * stylesheet principal is the triggeringPrincipal and the document that loads
-   * the stylesheet provides a loadingContext and hence the loadingPrincipal.
+   * This is the principal which caused the network load to start. I.e.
+   * this is the principal which provided the URL to be loaded. This is
+   * often the same as the LoadingPrincipal, but there are a few cases
+   * where that's not true.
    *
-   * If triggeringPrincipal and loadingPrincipal are the same, then
-   * triggeringPrincipal returns loadingPrincipal.
+   * For example for loads into an <iframe>, the LoadingPrincipal is always
+   * the principal of the parent document. However the TriggeringPrincipal
+   * is the principal of the document which provided the URL that the
+   * <iframe> is navigating to. This could be the previous document inside
+   * the <iframe> which set document.location. Or a document elsewhere in
+   * the frame tree which contained a <a target="..."> which targetted the
+   * <iframe>.
+   *
+   * If a stylesheet links to a sub-resource, like an @imported stylesheet,
+   * or a background image, then the TriggeringPrincipal is the principal
+   * of the stylesheet, while the LoadingPrincipal is the principal of the
+   * document being styled.
+   *
+   * The TriggeringPrincipal is never null.
    */
   readonly attribute nsIPrincipal triggeringPrincipal;
 
   /**
    * A C++-friendly version of triggeringPrincipal.
    */
   [noscript, notxpcom, nostdcall, binaryname(TriggeringPrincipal)]
   nsIPrincipal binaryTriggeringPrincipal();
 
   /**
-   * The loadingDocument of the channel.
-   *
-   * The loadingDocument of a channel is the document that requested the
-   * load of the resource. It is *not* the resource itself, it's the
-   * resource's caller or requester in which the load is happening.
+   * This is the ownerDocument of the LoadingNode. Unless the LoadingNode
+   * is a Document, in which case the LoadingDocument is the same as the
+   * LoadingNode.
    *
-   * <script> example: Assume a document who's origin is http://a.com embeds
-   * a script from http://b.com. The loadingDocument for the channel
-   * associated with the http://b.com script load is the document with origin
-   * http://a.com
-   *
-   * <iframe> example: Assume a document with origin http://a.com embeds
-   * <iframe src="http://b.com">. The loadingDocument for the channel associated
-   * with the http://b.com network request is the document who's origin is
-   * http://a.com. Now assume the iframe to http://b.com then further embeds
-   * <script src="http://c.com">. The loadingDocument for the channel associated
-   * with the http://c.com network request is the iframe with origin http://b.com.
-   *
-   * Warning: The loadingDocument can be null!
+   * For top-level loads, and for loads originating from workers, the
+   * LoadingDocument is null. When the LoadingDocument is not null, the
+   * LoadingPrincipal is set to the principal of the LoadingDocument.
    */
   readonly attribute nsIDOMDocument loadingDocument;
 
   /**
    * A C++-friendly version of loadingDocument (loadingNode).
-   * This is the node most proximally responsible for the load.
+   * This is the Node where the resulting resource will be used. I.e. it is
+   * the Node which will get access to the result of the request. (Where
+   * "get access to" might simply mean "embed" depending on the type of
+   * resource that is loaded).
+   *
+   * For example for an <img>/<video> it is the image/video element. For
+   * document loads inside <iframe> and <frame>s, the LoadingNode is the
+   * <iframe>/<frame> element. For an XMLHttpRequest, it is the Document
+   * which contained the JS which initiated the XHR. For a stylesheet, it
+   * is the Document that contains <link rel=stylesheet>.
+   *
+   * For loads triggered by the HTML pre-parser, the LoadingNode is the
+   * Document which is currently being parsed.
+   *
+   * For top-level loads, and for loads originating from workers, the
+   * LoadingNode is null. If the LoadingNode is non-null, then the
+   * LoadingPrincipal is the principal of the LoadingNode.
    */
   [noscript, notxpcom, nostdcall, binaryname(LoadingNode)]
   nsINode binaryLoadingNode();
 
   /**
    * The securityFlags of that channel.
    */
   readonly attribute nsSecurityFlags securityFlags;
--- a/netwerk/base/nsNetUtil.h
+++ b/netwerk/base/nsNetUtil.h
@@ -113,63 +113,22 @@ nsresult NS_NewFileURI(nsIURI **result,
 * * Call NS_NewChannelWithTriggeringPrincipal if the triggeringPrincipal
 *   is different from the loadingPrincipal.
 * * Call NS_NewChannelInternal() providing aLoadInfo object in cases where
 *   you already have loadInfo object, e.g in case of a channel redirect.
 *
 * @param aURI
 *        nsIURI from which to make a channel
 * @param aLoadingNode
-*        The loadingDocument of the channel.
-*        The element or document where the result of this request will be
-*        used. This is the document/element that will get access to the
-*        result of this request. For example for an image load, it's the
-*        document in which the image will be loaded. And for a CSS
-*        stylesheet it's the document whose rendering will be affected by
-*        the stylesheet.
-*        If possible, pass in the element which is performing the load. But
-*        if the load is coming from a JS API (such as XMLHttpRequest) or if
-*        the load might be coalesced across multiple elements (such as
-*        for <img>) then pass in the Document node instead.
-*        For loads that are not related to any document, such as loads coming
-*        from addons or internal browser features, use null here.
 * @param aLoadingPrincipal
-*        The loadingPrincipal of the channel.
-*        The principal of the document where the result of this request will
-*        be used.
-*        This defaults to the principal of aLoadingNode, so when aLoadingNode
-*        is passed this can be left as null. However for loads where
-*        aLoadingNode is null this argument must be passed.
-*        For example for loads from a WebWorker, pass the principal
-*        of that worker. For loads from an addon or from internal browser
-*        features, pass the system principal.
-*        This principal should almost always be the system principal if
-*        aLoadingNode is null. The only exception to this is for loads
-*        from WebWorkers since they don't have any nodes to be passed as
-*        aLoadingNode.
-*        Please note, aLoadingPrincipal is *not* the principal of the
-*        resource being loaded. But rather the principal of the context
-*        where the resource will be used.
 * @param aTriggeringPrincipal
-*        The triggeringPrincipal of the load.
-*        The triggeringPrincipal is the principal of the resource that caused
-*        this particular URL to be loaded.
-*        Most likely the triggeringPrincipal and the loadingPrincipal are
-*        identical, in which case the triggeringPrincipal can be left out.
-*        In some cases the loadingPrincipal and the triggeringPrincipal are
-*        different however, e.g. a stylesheet may import a subresource. In
-*        that case the principal of the stylesheet which contains the
-*        import command is the triggeringPrincipal, and the principal of
-*        the document whose rendering is affected is the loadingPrincipal.
 * @param aSecurityFlags
-*        The securityFlags of the channel.
-*        Any of the securityflags defined in nsILoadInfo.idl
 * @param aContentPolicyType
-*        The contentPolicyType of the channel.
-*        Any of the content types defined in nsIContentPolicy.idl
+*        These will be used as values for the nsILoadInfo object on the
+*        created channel. For details, see nsILoadInfo in nsILoadInfo.idl
 *
 * Please note, if you provide both a loadingNode and a loadingPrincipal,
 * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
 * But less error prone is to just supply a loadingNode.
 *
 * Keep in mind that URIs coming from a webpage should *never* use the
 * systemPrincipal as the loadingPrincipal.
 */
--- a/netwerk/protocol/websocket/nsIWebSocketChannel.idl
+++ b/netwerk/protocol/websocket/nsIWebSocketChannel.idl
@@ -68,57 +68,24 @@ interface nsIWebSocketChannel : nsISuppo
     /**
      * Sec-Websocket-Extensions response header value
      */
     readonly attribute ACString extensions;
 
     /**
      * Init the WebSocketChannel with LoadInfo arguments.
      * @param aLoadingNode
-     *        The loadingDocument of the channel.
-     *        The element or document where the result of this request will be
-     *        used. This is the document/element that will get access to the
-     *        result of this request. For example for an image load, it's the
-     *        document in which the image will be loaded. And for a CSS
-     *        stylesheet it's the document whose rendering will be affected by
-     *        the stylesheet.
-     *        For loads that are not related to any document, such as loads coming
-     *        from addons or internal browser features, use null here.
      * @param aLoadingPrincipal
-     *        The loadingPrincipal of the channel.
-     *        The principal of the document where the result of this request will
-     *        be used.
-     *        This defaults to the principal of aLoadingNode, so when aLoadingNode
-     *        is passed then aLoadingPrincipal can be left as null. However, for
-     *        loads where aLoadingNode is null this argument must be passed.
-     *        For example for loads from a WebWorker, pass the principal
-     *        of that worker. For loads from an addon or from internal browser
-     *        features, pass the system principal.
-     *        If aLoadingNode is null and the URI being loaded isn't coming from
-     *        a webpage, the principal should almost always be the systemPrincipal.
-     *        One exception to this is for loads from WebWorkers since they don't
-     *        have any nodes to be passed as aLoadingNode.
-     *        Please note, aLoadingPrincipal is *not* the principal of the
-     *        resource being loaded. But rather the principal of the context
-     *        where the resource will be used.
      * @param aTriggeringPrincipal
-     *        The triggeringPrincipal of the load.
-     *        The triggeringPrincipal is the principal of the resource that caused
-     *        this particular URL to be loaded.
-     *        For WebSockets, the loadingPrincipal and the triggeringPrincipal
-     *        are *always* identical.
      * @param aSecurityFlags
-     *        The securityFlags of the channel.
-     *        Any of the securityflags defined in nsILoadInfo.idl
      * @param aContentPolicyType
-     *        The contentPolicyType of the channel.
-     *        Any of the content types defined in nsIContentPolicy.idl
+     *        These will be used as values for the nsILoadInfo object on the
+     *        created channel. For details, see nsILoadInfo in nsILoadInfo.idl
      * @return reference to the new nsIChannel object
      *
-     *
      * Keep in mind that URIs coming from a webpage should *never* use the
      * systemPrincipal as the loadingPrincipal.
      *
      * Please note, if you provide both a loadingNode and a loadingPrincipal,
      * then loadingPrincipal must be equal to loadingNode->NodePrincipal().
      * But less error prone is to just supply a loadingNode.
      */
      void initLoadInfo(in nsIDOMNode aLoadingNode,