Address feedback

tools/dgeni/processors/categorizer.js

@@ -10,18 +10,23 @@ module.exports = function categorizer() {
   return {
     $runBefore: ['docs-processed'],
     $process: function (docs) {
-      docs.filter(doc => doc.docType === 'class').forEach(doc => visitClassDoc(doc));
+      docs.filter(doc => doc.docType === 'class').forEach(doc => decorateClassDoc(doc));
     }
   };
 
-  function visitClassDoc(classDoc) {
+  /**
+   * Decorates all class docs inside of the dgeni pipeline.
+   * - Methods and properties of a class-doc will be extracted into separate variables.
+   * - Identifies directives, services or NgModules and marks them them in class-doc.
+   **/
+  function decorateClassDoc(classDoc) {
     // Resolve all methods and properties from the classDoc. Includes inherited docs.
     classDoc.methods = resolveMethods(classDoc);
     classDoc.properties = resolveProperties(classDoc);
 
-    // Call visit hooks that can modify the method and property docs.
-    classDoc.methods.forEach(doc => visitMethodDoc(doc));
-    classDoc.properties.forEach(doc => visitPropertyDoc(doc));
+    // Call decorate hooks that can modify the method and property docs.
+    classDoc.methods.forEach(doc => decorateMethodDoc(doc));
+    classDoc.properties.forEach(doc => decoratePropertyDoc(doc));
 
     // Categorize the current visited classDoc into its Angular type.
     if (isDirective(classDoc)) {
@@ -34,14 +39,22 @@ module.exports = function categorizer() {
     }
   }
 
-  function visitMethodDoc(methodDoc) {
+  /**
+   * Method that will be called for each method doc. The parameters for the method-docs
+   * will be normalized, so that they can be easily used inside of dgeni templates.
+   **/
+  function decorateMethodDoc(methodDoc) {
     normalizeMethodParameters(methodDoc);
 
     // Mark methods with a `void` return type so we can omit show the return type in the docs.
     methodDoc.showReturns = methodDoc.returnType && methodDoc.returnType != 'void';
   }
 
-  function visitPropertyDoc(propertyDoc) {
+  /**
+   * Method that will be called for each property doc. Properties that are Angular inputs or
+   * outputs will be marked. Aliases for the inputs or outputs will be stored as well.
+   **/
+  function decoratePropertyDoc(propertyDoc) {
     propertyDoc.isDirectiveInput = isDirectiveInput(propertyDoc);
     propertyDoc.directiveInputAlias = getDirectiveInputAlias(propertyDoc);
 

tools/dgeni/processors/link-inherited-docs.js

@@ -40,6 +40,7 @@ module.exports = function linkInheritedDocs(readTypeScriptModules, tsParser) {
   }
 
   function resolveInheritedType(classSymbol) {
+    // Ensure that the symbol can be converted into a TypeScript ClassDeclaration.
     if (classSymbol.flags & ~ts.SymbolFlags.Class) {
       return;
     }