--- a/netwerk/base/public/nsIIOService.idl
+++ b/netwerk/base/public/nsIIOService.idl
@@ -62,20 +62,16 @@ interface nsIIOService : nsISupports
      * callers to specify whether this is a file or directory by
      * splitting this  into newDirURI() and newActualFileURI().
      */
     nsIURI newFileURI(in nsIFile aFile);
 
     /**
      * Creates a channel for a given URI.
      *
-     * 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.
-     *
      * @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
@@ -117,16 +113,19 @@ interface nsIIOService : nsISupports
      * @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
      * @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 newChannelFromURI2(in nsIURI aURI,
                                   in nsIDOMNode aLoadingNode,
                                   in nsIPrincipal aLoadingPrincipal,
                                   in nsIPrincipal aTriggeringPrincipal,
                                   in unsigned long aSecurityFlags,
                                   in unsigned long aContentPolicyType);
 

--- a/netwerk/base/public/nsIIOService2.idl
+++ b/netwerk/base/public/nsIIOService2.idl
@@ -28,20 +28,16 @@ interface nsIIOService2 : nsIIOService
    * if there is no link, until application code runs and can turn off
    * this management.
    */
   attribute boolean manageOfflineStatus;
 
   /**
    * Creates a channel for a given URI.
    *
-   * 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.
-   *
    * @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
@@ -88,16 +84,19 @@ interface nsIIOService2 : nsIIOService
    * @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
    * @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,
                                               in unsigned long aProxyFlags,
                                               in nsIDOMNode aLoadingNode,
                                               in nsIPrincipal aLoadingPrincipal,
                                               in nsIPrincipal aTriggeringPrincipal,
                                               in unsigned long aSecurityFlags,

--- a/netwerk/base/public/nsNetUtil.h
+++ b/netwerk/base/public/nsNetUtil.h
@@ -188,19 +188,26 @@ NS_NewFileURI(nsIURI* *result,
 }
 
 /*
 * How to create a new Channel, using NS_NewChannel,
 * NS_NewChannelWithTriggeringPrincipal, NS_OpenURI,
 * NS_NewInputStreamChannel, NS_NewChannelInternal
 * and it's variations:
 *
-* 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.
+* What specific API function to use:
+* * The NS_NewChannelInternal functions should almost never be directly
+*   called outside of necko code.
+* * If possible, use NS_NewChannel() providing a loading *nsINode*
+* * If no loading *nsINode* is avaialable, call NS_NewChannel() providing
+*   a loading *nsIPrincipal*.
+* * 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
@@ -242,26 +249,19 @@ NS_NewFileURI(nsIURI* *result,
 *        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
 *
-* What specific API function to use:
-* * The NS_NewChannelInternal functions should almost never be directly
-*   called outside of necko code.
-* * If possible, use NS_NewChannel() providing a loading *nsINode*
-* * If no loading *nsINode* is avaialable, call NS_NewChannel() providing
-*   a loading *nsIPrincipal*.
-* * 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.
+* 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.
 */
 inline nsresult
 NS_NewChannelInternal(nsIChannel**           outChannel,
                       nsIURI*                aUri,
                       nsINode*               aLoadingNode,
                       nsIPrincipal*          aLoadingPrincipal,
                       nsIPrincipal*          aTriggeringPrincipal,
                       nsSecurityFlags        aSecurityFlags,