Restructure slightly based on Tim's comment:

https://github.com/civicrm/civicrm-dev-docs/pull/425#issuecomment-338253390

docs/framework/asset-builder.md

@@ -40,11 +40,6 @@ For example, suppose we wanted to define a static file named
 `api-fields.json` which lists all the fields of all the API entities.
 
 ```php
-// Get the URL to `api-fields.json`.
-$url = \Civi::service('asset_builder')->getUrl('api-fields.json');
-
-...
-
 // Define the content of `api-fields.json` using `hook_civicrm_buildAsset`.
 function mymodule_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
   if ($asset !== 'api-fields.json') return;
@@ -60,6 +55,16 @@ function mymodule_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
 }
 ```
 
+Check it is functioning correctly with:
+```
+$ cv ev '$x = \Civi::service("asset_builder")->render("api-fields.json"); echo $x["content"];'
+```
+
+Get the generated URL:
+```
+$ cv ev 'return \Civi::service("asset_builder")->getURL("api-fields.json");'
+```
+
 !!! note "What does `getUrl(...)` do?"
 
     In normal/production mode, `getUrl(...)` checks to see if the asset
@@ -77,27 +82,9 @@ different permutations or configurations? Add parameters (aka `$params`).
 
 For example, we might want a copy of `api-fields.json` which only includes a
 handful of chosen entities.  Simply pass the chosen entities into
-`getUrl()`, then update the definition to use `$params['entities']`, as in:
+`getUrl()`, then update the definition to use `$params['entities']`.
 
 ```php
-// Get the URL to `api-fields.json`. This variant only includes
-// a few contact-related entities.
-$contactEntitiesUrl = \Civi::service('asset_builder')
-  ->getUrl('api-fields.json', array(
-    'entities' => array('Contact', 'Phone', 'Email', 'Address'),
-  )
-);
-
-// Get the URL to `api-fields.json`. This variant only includes
-// a few case-related entities.
-$caseEntitiesUrl = \Civi::service('asset_builder')
-  ->getUrl('api-fields.json', array(
-    'entities' => array('Case', 'Activity', 'Relationship'),
-  )
-);
-
-...
-
 // Define the content of `api-fields.json` using `hook_civicrm_buildAsset`.
 function mymodule_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
   if ($asset !== 'api-fields.json') return;
@@ -112,6 +99,16 @@ function mymodule_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
 }
 ```
 
+Get the generated URL for `api-fields.json` for a few contact-related entities:
+```
+$ cv ev 'return \Civi::service("asset_builder")->getURL("api-fields.json", array("entities" => array("Contact", "Phone", "Email", "Address")));'
+```
+
+Get the generated URL for `api-fields.json` for a few case-related entities:
+```
+$ cv ev 'return \Civi::service("asset_builder")->getURL("api-fields.json", array("entities" => array("Case", "Activity", "Relationship")));'
+```
+
 !!! note "Note: Parameters and caching"
     Each combination of (`$asset`,`$params`) will be cached separately.
 
@@ -159,20 +156,14 @@ Create `css/my_css_template.css` with content:
 In `myextension.php`:
 
 ```php
-function myextension_civicrm_coreResourceList(&$list, $region) {
-   ...
-   // To include the file without any processing we could use:
-   // CRM_Core_Resources::singleton()->addStyleFile('org.example.myextension', 'css/my_css.css');
-   // replace that with the following:
-   
-   // use the asset_builder service to get the url of an asset labeled 'mycss'
-   $url = \Civi::service('asset_builder')->getUrl('mycss');
-
-   // load the processed style on the page 
-   CRM_Core_Resources::singleton()->addStyleUrl($url);
-}
-
-// Use the buildAsset hook to process the css template
+/**
+ * Implements hook_civicrm_buildAsset().
+ *
+ * Use hook_civicrm_buildAsset() to define the asset 'mycss'
+ * It locates the css template in the extension and the required image from core
+ * and substitutes the image path into the css template returning the value via
+ * the $content parameter.
+ */
 function myextension_civicrm_buildAsset($asset, $params, &$mimetype, &$content) {
   // Check for the asset of interest
   if ($asset !== 'mycss') return;
@@ -186,25 +177,45 @@ function myextension_civicrm_buildAsset($asset, $params, &$mimetype, &$content)
   // Get the URL of the image we want from Core
   // Note that the 'civicrm' string here is a special to refer to the installation location of the core files
   $url = \Civi::resources()->getUrl('civicrm', 'i/logo_sm.png');
-  
+
   // Replace the LOGO_URL token in the file with the actual url
   // Note that $content is passed by reference to this hook function
   $content = str_replace('LOGO_URL', $url, $raw);
-  
+
   // Set the mimetype appropriately for the type of content
   // Note that $mimetype is passed by reference to this hook function
   $mimetype = 'text/css';
 }
 ```
 
-Check it is functioning correctly with:
+Check it is functioning correctly:
 ```
-$ cv ev '$x = \Civi::service("asset_builder")->render("mycss"); echo $x["content"];' 
+$ cv ev '$x = \Civi::service("asset_builder")->render("mycss"); echo $x["content"];'
 ```
 
-To see the generated URL use:
+Get the generated URL:
+```
+$ cv ev 'return \Civi::service("asset_builder")->getURL("mycss");'
 ```
-$ cv ev 'return \Civi::service("asset_builder")->getURL("mycss");' 
+
+Now we can use our newly defined asset in place of a static css file in `myextension.php`:
+
+```php
+/**
+ * Implements hook_civicrm_coreResourceList().
+ */
+function myextension_civicrm_coreResourceList(&$list, $region) {
+   ...
+   // To include the file without any processing we could use:
+   // CRM_Core_Resources::singleton()->addStyleFile('org.example.myextension', 'css/my_css.css');
+   // replace that with the following:
+
+   // use the asset_builder service to get the url of an asset labeled 'mycss'
+   $url = \Civi::service('asset_builder')->getUrl('mycss');
+
+   // load the processed style on the page
+   CRM_Core_Resources::singleton()->addStyleUrl($url);
+}
 ```
 
 Notes: