fixup! docs: more ngProp docs

Narretz · Narretz · commit 127300f4d60e · 2018-07-18T20:50:14.000+02:00
diff --git a/src/ng/compile.js b/src/ng/compile.js
@@ -1050,6 +1050,22 @@
  * @restrict A
  * @element ANY
  *
+ * @usage
+ *
+ * ```html
+ * <ANY ng-prop-propname="expression">
+ * </ANY>
+ * ```
+ *
+ * or with uppercase letters in property (e.g. "propName"):
+ *
+ *
+ * ```html
+ * <ANY ng-prop-prop_name="expression">
+ * </ANY>
+ * ```
+ *
+ *
  * @description
  * The `ngProp` directive binds an expression to a DOM element property.
  * `ngProp` allows writing to arbitrary properties by including
@@ -1067,7 +1083,8 @@
  *
  * Since HTML attributes are case-insensitive, camelCase properties like `innerHTML` must be escaped.
  * AngularJS uses the underscore (_) in front of a character to indicate that it is uppercase, so
- * `innerHTML`  must be written as `ng-prop-inner_h_t_m_l="expression"`.
+ * `innerHTML`  must be written as `ng-prop-inner_h_t_m_l="expression"` (Note that this is just an
+ * example, and for binding HTML {@link ngBindHtml} should be used.
  *
  * ## Security
  *
@@ -1076,26 +1093,29 @@
  * malicious code.
  * For this reason, `ngProp` applies Strict Contextual Escaping with the {@link ng.$sce $sce service}.
  * This means vulnerable properties require their content to be "trusted", based on the
- * context of the property. For example, the `iframe[src]` property is in the `RESOURCE_URL` context and
- * `innerHTML` is in the `HTML` context.
- * If you trust the source of the content, you can use {@link ng.$sce#trustAs $sce.trustAs()}, (and
- * the shortcut methods {@link ng.$sce#trustAsHtml $sce.trustAsHtml()} et al.) to create an object
- * that wraps the value and is marked as safe. However, you should only do this if you are sure the
- * value is safe.
+ * context of the property. For example, the `innerHTML` is in the `HTML` context, and the
+ * `iframe.src` property is in the `RESOURCE_URL` context, which requires that values written to
+ * this property are trusted as a `RESOURCE_URL`.
+ *
+ * This can be set explicitly by calling $sce.trustAs(type, value) on the value that is
+ * trusted before passing it to the `ng-prop-*` directive. There are exist shorthand methods for
+ * each context type in the form of {@link ng.$sce#trustAsResourceUrl $sce.trustAsResourceUrl()} et al.
+ *
+ * In some cases you can also rely upon automatic sanitization of untrusted values - see below.
  *
  * Based on the context, other options may exist to mark a value as trusted / configure the behavior
- * of {@link ng.$sce}. For example, to the `RESOURCE_URL` context to specific origins, use the
- * {@link $sceDelegateProvider#resourceUrlWhitelist $sceDelegateProvider#resourceUrlWhitelist} and
- * {@link $sceDelegateProvider#resourceUrlBlacklist $sceDelegateProvider#resourceUrlBlacklist}.
+ * of {@link ng.$sce}. For example, to restrict the `RESOURCE_URL` context to specific origins, use
+ * the {@link $sceDelegateProvider#resourceUrlWhitelist resourceUrlWhitelist()}
+ * and {@link $sceDelegateProvider#resourceUrlBlacklist resourceUrlBlacklist()}.
  *
  * {@link ng.$sce#what-trusted-context-types-are-supported- Find out more about the different context types}.
  *
- * ### Sanitization
+ * ### HTML Sanitization
  *
- * By default, `$sce` will throw an error if it detects untrusted content, and will not bind the
+ * By default, `$sce` will throw an error if it detects untrusted HTML content, and will not bind the
  * content.
  * However, if you include the {@link ngSanitize ngSanitize module}, it will try to sanitize the
- * potentially dangerous content, e.g. strip non-whitelisted tags and attributes when binding to
+ * potentially dangerous HTML, e.g. strip non-whitelisted tags and attributes when binding to
  * `innerHTML`.
  *
  * @example
@@ -1161,7 +1181,7 @@
  *
  *
  * @example
- * ### Binding unsafe content with ngSanitize
+ * ### Binding to innerHTML with ngSanitize
  *
  * <example name="ngProp" module="exampleNgProp" deps="angular-sanitize.js">
  *   <file name="app.js">
@@ -1222,11 +1242,27 @@
  * @restrict A
  * @element ANY
  *
+ * @usage
+ *
+ * ```html
+ * <ANY ng-on-eventname="expression">
+ * </ANY>
+ * ```
+ *
+ * or with uppercase letters in property (e.g. "eventName"):
+ *
+ *
+ * ```html
+ * <ANY ng-on-event_name="expression">
+ * </ANY>
+ * ```
+ *
  * @description
- * The `ngOn` directive adds an event listener to a DOM element, and evaluates an expression
- * when the event is fired.
+ * The `ngOn` directive adds an event listener to a DOM element via
+ * {@link angular.element angular.element().on()}, and evaluates an expression when the event is
+ * fired.
  * `ngOn` allows adding listeners for arbitrary events by including
- * the event name in the attribute, e.g. `ng-on-drop="onDrop()"` executes the 'onDrop' expression
+ * the event name in the attribute, e.g. `ng-on-drop="onDrop()"` executes the 'onDrop()' expression
  * when the `drop` event is fired.
  *
  * AngularJS provides specific directives for many events, such as {@link ngClick}, so in most
@@ -1237,6 +1273,12 @@
  * [custom events](https://developer.mozilla.org/docs/Web/Guide/Events/Creating_and_triggering_events)
  * that are fired like normal DOM events.
  *
+ * ## Binding to camelCase properties
+ *
+ * Since HTML attributes are case-insensitive, camelCase properties like `myEvent` must be escaped.
+ * AngularJS uses the underscore (_) in front of a character to indicate that it is uppercase, so
+ * `myEvent` must be written as `ng-on-my_event="expression"`.
+ *
  * @example
  * ### Bind to built-in DOM events
  *
