Show directive selector in generated API docs

[jelbourn]

The API docs do not currently show the selector for directives. We should surface this information. This will involve collecting the information in categorizer.js and then adding it to the class.template.html.

Only the md- selectors should be shown (not the mat- selectors).

The follow-up would be styling the information on material.angular.io.

[jbh]

Is there a certain way this should be formatted/templated within class.template.html? Similar to propertyList and methodList or something simpler within class.template.html itself? At the moment, I have my fork grabbing the selectors from the classDoc object by traversing the decorators and parsing the arguments. This leaves me with an array of string selector names. That might not need to be as verbose as the methodList and propertyList.

// categorizer.js
/**
 * Function that walks through all inherited docs and collects public selectors.
 * Only the md- selectors should be shown (not the mat- selectors).
 */
function resolveMdSelectors(classDoc) {
  let onlyMdSelectors = [];

  classDoc.decorators.forEach(function(decorator) {
    decorator.arguments.forEach(function(argument) {
      // Split the stringified object by newline to get each part
      let argParts = argument.split('\n');
      // Get the selector line with `selector: \'` in order to ignore such things as `{selector: MAT_ELEMENTS_SELECTOR}`
      let selectorLine = argParts.filter(argPart => argPart.indexOf('selector: \'') !== -1)[0];

      if (selectorLine) {
        // Set the bookending ticks for grabbing the selectors
        let firstTick = selectorLine.indexOf('\'') + 1;
        let lastTick = selectorLine.indexOf('\'', firstTick);
        // Get the selectors.
        let selectors = selectorLine.substring(firstTick, lastTick).replace(/ /g, '').split(',');
        onlyMdSelectors = selectors.filter(selector => selector.indexOf('md') !== -1);
      }
    });
  });

  return onlyMdSelectors;
}

If there's a better way of getting the selectors, I'd be happy to clean that up.

[jelbourn]

@jbh check out the existing getDirectiveExportAs function which does something similar.

As for how to show this information in the template- I was thinking it should go directly underneath the class name for any @Directive or @Component (wrapped in an element with its own class).

Thinking about this more, we should also have a blacklist for deprecated selectors. This would include, for now:
[portal], [portalHost], textarea[md-autosize], [overlay-origin], [connected-overlay]

[jbh]

@jelbourn To clarify the blacklist, do you mean a blacklist constant to be maintained withincategorizer.js? Anything within this blacklist would be excluded from the selector list?

Also, when you said

Only the md- selectors should be shown (not the mat- selectors).

Did you mean to just exclude mat- selectors, or did you mean to only include selectors with md in it period?

[jelbourn]

@jbh yeah, I would just put the blacklist there for now. Anything in that list would be ignored when decorating the doc object.

For prefixes, yes- I meant anything with the mat prefix should be omitted.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}