Bug 767134 didn't add documentation. Add required documentation. This might also mean more crisply defining what the aRequestPrincipal should be for all the contentpolicy calls.

First attempt. Not sure what the documentation etiquette is, but I am sure the review will point me towards the right path.

Comment on attachment 673500 [details] [diff] [review] Documentation for aRequestPrincipal >+ * inapplicable. Note that loads caused by data: >+ * and about: iframes pass the iframe URI as the >+ * requestOrigin, but the iframe inherits the >+ * principal from the parent by default. Is this necessarily true? I think this is true for navigation, but not for, say, an <img> load in such an iframe, since that goes through NS_CheckContentLoadPolicy, which passes in the principal codebase as the location. Also, javascript: has the same behavior as data:. And about: generally does not; about:blank is special. >+ * argument. Currently, not set for any loads other >+ * navigation events. "other than"? But this seems to not be the case; anything using NS_CheckContentLoadPolicy is passing in a principal. r=me with the above fixed.

Comment on attachment 674542 [details] [diff] [review] Documentation for aRequestPrincipal r=bz Carrying over the r+ from bz. @bz: If you have time to take a look and confirm that the documentation looks right, that would be great. I will wait for a couple of days before requesting check-in.

Looks reasonable.

In which cases would the caller be non-gecko code?

Any extension (e.g., noscript, adblock) There might be other cases. bz/dveditz probably know more.

Is there a bug to go through the code and add the Request Principal in gecko code when it's missing?

If I am not wrong, Gecko code should be using NS_CheckContentLoadPolicy anyways, and that should set the requestprincipal properly. Can you point me to examples where it's missing?