Fixing up comments and README.md

packages/style-engine/README.md

@@ -86,7 +86,7 @@ array(
 */
 ```
 
-The default block style support can be extended by passing metadata in the options.
+The default block style support definitions can be extended by passing metadata in the options. 
 
 ```php
 $block_attributes =  array(
@@ -121,6 +121,8 @@ array(
 */
 ```
 
+Note: CSS properties must be supported by [safecss_filter_attr](https://developer.wordpress.org/reference/functions/safecss_filter_attr/), otherwise you can allow non-supported CSS using the filter [safecss_filter_attr_allow_css](https://developer.wordpress.org/reference/hooks/safecss_filter_attr_allow_css/).
+
 ### wp_style_engine_get_stylesheet_from_css_rules()
 
 Use this function to compile and return a stylesheet for any CSS rules. The Style Engine will automatically merge declarations and combine selectors.

packages/style-engine/class-wp-style-engine-block-style-metadata.php

@@ -18,7 +18,7 @@
  */
 class WP_Style_Engine_Block_Style_Metadata {
 	/**
-	 * The original metadata.
+	 * A variable to cache original metadata.
 	 *
 	 * @var array
 	 */
@@ -34,9 +34,6 @@ class WP_Style_Engine_Block_Style_Metadata {
 	/**
 	 * Constructor for this object.
 	 *
-	 * If a `$declarations` array is passed, it will be used to populate
-	 * the initial $declarations prop of the object by calling add_declarations().
-	 *
 	 * @param array $base_metadata An associative array of block style metadata to extend.
 	 */
 	public function __construct( $base_metadata = array() ) {
@@ -45,7 +42,7 @@ public function __construct( $base_metadata = array() ) {
 	}
 
 	/**
-	 * Add block style metadata.
+	 * Adds block style metadata.
 	 *
 	 * @param array $metadata The $metadata.
 	 *
@@ -78,7 +75,7 @@ public function add_metadata( $metadata = array() ) {
 	}
 
 	/**
-	 * Get the metadata array.
+	 * Returns merged metadata.
 	 *
 	 * @param array $path A path to an array item in static::$merged_block_support_metadata.
 	 * @return array