docs: Show directive selector in generated API docs (#4139)

Fixes #3983

Author: Josh Hall

tools/dgeni/processors/categorizer.js

@@ -1,3 +1,16 @@
+/**
+ * We want to avoid emitting selectors that are deprecated but don't have a way to mark
+ * them as such in the source code. Thus, we maintain a separate blacklist of selectors
+ * that should not be emitted in the documentation.
+ */
+const SELECTOR_BLACKLIST  = new Set([
+  '[portal]',
+  '[portalHost]',
+  'textarea[md-autosize]',
+  '[overlay-origin]',
+  '[connected-overlay]',
+]);
+
 /**
  * Processor to add properties to docs objects.
  *
@@ -29,11 +42,12 @@ module.exports = function categorizer() {
     classDoc.properties.forEach(doc => decoratePropertyDoc(doc));
 
     decoratePublicDoc(classDoc);
-    
+
     // Categorize the current visited classDoc into its Angular type.
     if (isDirective(classDoc)) {
       classDoc.isDirective = true;
       classDoc.directiveExportAs = getDirectiveExportAs(classDoc);
+      classDoc.directiveSelectors =  getDirectiveSelectors(classDoc);
     } else if (isService(classDoc)) {
       classDoc.isService = true;
     } else if (isNgModule(classDoc)) {
@@ -171,6 +185,18 @@ function getDirectiveOutputAlias(doc) {
   return isDirectiveOutput(doc) ? doc.decorators.find(d => d.name == 'Output').arguments[0] : '';
 }
 
+function getDirectiveSelectors(classDoc) {
+  let metadata = classDoc.decorators
+    .find(d => d.name === 'Component' || d.name === 'Directive').arguments[0];
+
+  let selectorMatches = /selector\s*:\s*(?:"|')([^']*?)(?:"|')/g.exec(metadata);
+  selectorMatches = selectorMatches && selectorMatches[1];
+
+  return selectorMatches ? selectorMatches.split(/\s*,\s*/)
+    .filter(s => s !== '' && !s.includes('mat') && !SELECTOR_BLACKLIST.has(s))
+    : selectorMatches;
+}
+
 function getDirectiveExportAs(doc) {
   let metadata = doc.decorators
       .find(d => d.name === 'Component' || d.name === 'Directive').arguments[0];

tools/dgeni/templates/class.template.html

@@ -3,14 +3,23 @@ <h4 class="docs-api-h4 docs-api-class-name">
 </h4>
 <p class="docs-api-class-description">{$ class.description $}</p>
 
+{%- if class.directiveSelectors -%}
+<div class="docs-api-directive-selectors">
+  <span class="docs-api-class-selector-label">selector:</span>
+  {% for s in class.directiveSelectors %}
+    <span class="docs-api-class-selector-name">{$ s $}</span>
+  {% endfor %}
+</div>
+{%- endif -%}
+
 {%- if class.directiveExportAs -%}
 <span class="docs-api-h4 docs-api-class-export-label">Exported as:</span>
 <span class="docs-api-class-export-name">{$ class.directiveExportAs $}</span>
 {%- endif -%}
 
 {%- if class.isDeprecated -%}
 <div class="docs-api-class-deprecated-marker">Deprecated</div>
-{%- endif -%}   
+{%- endif -%}
 
 {$ propertyList(class.properties) $}