Added examples in docs, added IApiDefinitionReferenceParts to avoid confusion, changed IScopePackageName to IScopedPackageName

dgaeta · dgaeta · commit f7bcd53af1bb · 2017-02-15T18:13:47.000-08:00
diff --git a/api-extractor/src/ApiDefinitionReference.ts b/api-extractor/src/ApiDefinitionReference.ts
@@ -1,7 +1,45 @@
+/**
+ * An API definition reference that is used to locate the documentation of exported 
+ * API items that may or may not belong to an external package. 
+ * 
+ * The format of the API definition reference is: 
+ * scopeName/packageName:exportName.memberName
+ * 
+ * The following are valid API definition references: 
+ * \@microsoft/sp-core-library:DisplayMode
+ * \@microsoft/sp-core-library:Guid
+ * \@microsoft/sp-core-library:Guid.equals
+ * es6-collections:Map
+ */
+export interface IApiDefinintionReferenceParts {
+  /**
+   * This is an optional property to denote that a package name is scoped under this name.
+   * For example, a common case is when having the '@microsoft' scope name in the 
+   * API definition reference: '\@microsoft/sp-core-library'.
+   */
+  scopeName: string;
+  /**
+   * The name of the package that the exportName belongs to.
+   */
+  packageName: string;
+  /**
+   * The name of the export API item.
+   */
+  exportName: string;
+  /**
+   * The name of the member API item. 
+   */
+  memberName: string;
+}
+
 /**
  * A scope and package name are semantic information within an API reference expression.
+ * If there is no scope or package, then the corresponding values will be an empty string.
+ * 
+ * Example: '@microsoft/Utilities' -> \{ scope: '@microsoft', package: 'Utilities' \}
+ * Example: 'Utilities' -> \{ scope: '', package: 'Utilities' \}
  */
-export interface IScopePackageName {
+export interface IScopedPackageName {
   /**
    * The scope name of an API reference expression.
    */
@@ -14,17 +52,7 @@ export interface IScopePackageName {
 }
 
 /**
- * An API definition reference that is used to locate the documentation of exported 
- * API items that may or may not belong to an external package. 
- * 
- * The format of the API definition reference is: 
- * scopeName/packageName:exportName.memberName
- * 
- * The following are valid API definition references: 
- * \@microsoft/sp-core-library:DisplayMode
- * \@microsoft/sp-core-library:Guid
- * \@microsoft/sp-core-library:Guid.equals
- * es6-collections:Map
+ * {@inheritdoc IApiDefinintionReferenceParts}
  */
 export default class ApiDefinitionReference {
   /**
@@ -44,33 +72,28 @@ export default class ApiDefinitionReference {
   private static _exportRegEx: RegExp =  /^\w+/;
 
   /**
-   * This is an optional property to denote that a package name is scoped under this name.
-   * For example, a common case is when having the '@microsoft' scope name in the 
-   * API definition reference: '\@microsoft/sp-core-library'.
+   * {@inheritdoc IApiDefinintionReferenceParts.scopeName}
    */
   public scopeName: string;
   /**
-   * The name of the package that the exportName belongs to.
+   * {@inheritdoc IApiDefinintionReferenceParts.packageName}
    */
   public packageName: string;
   /**
-   * The name of the export API item.
+   * {@inheritdoc IApiDefinintionReferenceParts.exportName}
    */
   public exportName: string;
   /**
-   * The name of the member API item. 
+   * {@inheritdoc IApiDefinintionReferenceParts.memberName}
    */
   public memberName: string;
 
   /**
    * Creates an ApiDefinitionReference instance given strings that symbolize the public
    * properties of ApiDefinitionReference.
    */
-  public static createFromParts(scopeName: string,
-    packageName: string,
-    exportName: string,
-    memberName: string): ApiDefinitionReference {
-    return new ApiDefinitionReference(scopeName, packageName, exportName, memberName);
+  public static createFromParts(parts: IApiDefinintionReferenceParts): ApiDefinitionReference {
+    return new ApiDefinitionReference(parts);
   }
 
   /**
@@ -86,26 +109,28 @@ export default class ApiDefinitionReference {
       return;
     }
 
-    let scopeName: string = '';
-    let packageName: string = '';
-    let exportName: string = '';
-    let memberName: string = '';
+    const apiDefRefParts: IApiDefinintionReferenceParts = {
+      scopeName: '',
+      packageName: '',
+      exportName: '',
+      memberName: ''
+    };
 
     // E.g. @microsoft/sp-core-library:Guid.equals
     let parts: string[] = apiReferenceExpr.match(ApiDefinitionReference._packageRegEx);
     if (parts) {
       // parts[1] is of the form ‘@microsoft/sp-core-library’ or ‘sp-core-library’
-      const scopePackageName: IScopePackageName = ApiDefinitionReference.parseScopedPackageName(parts[1]);
-      scopeName = scopePackageName.scope;
-      packageName = scopePackageName.package;
+      const scopePackageName: IScopedPackageName = ApiDefinitionReference.parseScopedPackageName(parts[1]);
+      apiDefRefParts.scopeName = scopePackageName.scope;
+      apiDefRefParts.packageName = scopePackageName.package;
       apiReferenceExpr = parts[2]; // e.g. Guid.equals
     }
 
     // E.g. Guid.equals
     parts = apiReferenceExpr.match(ApiDefinitionReference._memberRegEx);
     if (parts) {
-      exportName = parts[1]; // e.g. Guid, can never be undefined
-      memberName = parts[2] ? parts[2] : ''; // e.g. equals
+      apiDefRefParts.exportName = parts[1]; // e.g. Guid, can never be undefined
+      apiDefRefParts.memberName = parts[2] ? parts[2] : ''; // e.g. equals
     } else {
       // the export name is required
        throw reportError(`Api reference expression contains invalid characters: ${apiReferenceExpr}`);
@@ -115,15 +140,15 @@ export default class ApiDefinitionReference {
       throw reportError(`Api reference expression contains invalid characters: ${apiReferenceExpr}`);
     }
 
-    return ApiDefinitionReference.createFromParts(scopeName, packageName, exportName, memberName);
+    return ApiDefinitionReference.createFromParts(apiDefRefParts);
   }
 
   /**
    * For a scoped NPM package name this separates the scope and package parts.  For example:
    * parseScopedPackageName('@my-scope/myproject') = { scope: '@my-scope', package: 'myproject' }
    * parseScopedPackageName('myproject') = { scope: '', package: 'myproject' }
    */
-  public static parseScopedPackageName(scopedName: string): IScopePackageName {
+  public static parseScopedPackageName(scopedName: string): IScopedPackageName {
     if (scopedName.substr(0, 1) !== '@') {
       return { scope: '', package: scopedName };
     }
@@ -136,25 +161,11 @@ export default class ApiDefinitionReference {
     }
   }
 
-  /**
-   * Seperates the name property of an ApiPackage into a scope name and the actual 
-   * name of the package.
-   */
-  public static parseApiPackageName(apiPackageName: string): IScopePackageName {
-    const slashIndex: number = apiPackageName.indexOf('/');
-    if (slashIndex >= 0) {
-      return {
-        scope: apiPackageName.substr(0, slashIndex),
-        package: apiPackageName.substr(slashIndex + 1)
-      };
-    } else {
-      return { scope: '', package: apiPackageName.substr(slashIndex + 1) };
-    }
-  }
-
   /**
    * Stringifies the ApiDefinitionReferenceOptions up and including the
    * scope and package name.
+   * 
+   * Example output: '@microsoft/Utilities'
    */
   public toScopePackageString(): string {
     let result: string = '';
@@ -169,6 +180,8 @@ export default class ApiDefinitionReference {
   /**
    * Stringifies the ApiDefinitionReferenceOptions up and including the
    * scope, package and export name.
+   * 
+   * Example output: '@microsoft/Utilities.Parse'
    */
   public toExportString(): string {
     let result: string = this.toScopePackageString();
@@ -181,15 +194,17 @@ export default class ApiDefinitionReference {
   /**
    * Stringifies the ApiDefinitionReferenceOptions up and including the
    * scope, package, export and member name.
+   * 
+   * Example output: '@microsoft/Utilities.Parse.parseJsonToString'
    */
   public toMemberString(): string {
     return this.toExportString() + `.${this.memberName}`;
   }
 
-  private constructor(scopeName: string, packageName: string, exportName: string, memberName: string) {
-    this.scopeName = scopeName;
-    this.packageName = packageName;
-    this.exportName = exportName;
-    this.memberName = memberName;
+  private constructor(parts: IApiDefinintionReferenceParts) {
+    this.scopeName = parts.scopeName;
+    this.packageName = parts.packageName;
+    this.exportName = parts.exportName;
+    this.memberName = parts.memberName;
   }
 }
diff --git a/api-extractor/src/DebugRun.ts b/api-extractor/src/DebugRun.ts
@@ -6,7 +6,7 @@ import * as os from 'os';
 import Extractor from './Extractor';
 import ApiFileGenerator from './generators/ApiFileGenerator';
 import ApiJsonGenerator from './generators/ApiJsonGenerator';
-import ApiDefinitionReference from './ApiDefinitionReference';
+import ApiDefinitionReference, { IApiDefinintionReferenceParts } from './ApiDefinitionReference';
 
 const compilerOptions: ts.CompilerOptions = {
   target: ts.ScriptTarget.ES5,
@@ -32,13 +32,14 @@ extractor.loadExternalPackages('./testInputs/external-api-json');
 extractor.analyze({entryPointFile: './testInputs/example2/index.ts',
   otherFiles: []});
 
-const externalPackageApiRef: ApiDefinitionReference = ApiDefinitionReference.createFromParts(
-  '',
-  'es6-collections',
-  '',
-  ''
-);
-console.log(extractor.docItemLoader.getPackage(externalPackageApiRef, console.log));
+const externalPackageApiRef: IApiDefinintionReferenceParts = {
+  scopeName: '',
+  packageName: 'es6-collections',
+  exportName: '',
+  memberName: ''
+};
+const apiDefinitionRef: ApiDefinitionReference = ApiDefinitionReference.createFromParts(externalPackageApiRef);
+console.log(extractor.docItemLoader.getPackage(apiDefinitionRef, console.log));
 
 const apiFileGenerator: ApiFileGenerator = new ApiFileGenerator();
 apiFileGenerator.writeApiFile('./lib/DebugRun.api.ts', extractor);
diff --git a/api-extractor/src/DocItemLoader.ts b/api-extractor/src/DocItemLoader.ts
@@ -2,7 +2,7 @@ import * as fsx from 'fs-extra';
 import * as os  from 'os';
 import * as path from 'path';
 import { IDocItem, IDocPackage, IDocMember } from './IDocItem';
-import ApiDefinitionReference, { IScopePackageName } from './ApiDefinitionReference';
+import ApiDefinitionReference, { IScopedPackageName, IApiDefinintionReferenceParts } from './ApiDefinitionReference';
 import ApiItem from './definitions/ApiItem';
 import ApiItemContainer from './definitions/ApiItemContainer';
 import ApiPackage from './definitions/ApiPackage';
@@ -56,21 +56,10 @@ export default class DocItemLoader {
     apiPackage: ApiPackage,
     reportError: (message: string) => void): ResolvedApiItem {
 
-    const scopePackageName: IScopePackageName = ApiDefinitionReference.parseApiPackageName(
-      path.dirname(apiPackage.name)
-    );
-    const currentScopeName: string = scopePackageName.scope;
-    const currentPackageName: string = scopePackageName.package;
-
-    const packageNameMatch: boolean = apiDefinitionRef.packageName ?
-      apiDefinitionRef.packageName === currentPackageName : true;
-    const scopeNameMatch: boolean = apiDefinitionRef.scopeName ?
-      apiDefinitionRef.scopeName === currentScopeName : true;
-
     // If there is a packageName then there must be a scopeName, and they 
     // both must match the current scope and package we are in.
-    // We can take advantage of '&&' being evaluated left to right. 
-    if (packageNameMatch && scopeNameMatch) {
+    // We can take advantage of '&&' being evaluated left to right.
+    if (!apiDefinitionRef.packageName && !apiDefinitionRef.scopeName) {
       // Resolution for local references 
       return this.resolveLocalReferences(apiDefinitionRef, apiPackage, reportError);
     } else {
diff --git a/api-extractor/testInputs/example3/example3-output.json b/api-extractor/testInputs/example3/example3-output.json
@@ -87,7 +87,7 @@
       "remarks": [],
       "isBeta": false
     },
-    "inheritLocalOptionThreeFunction": {
+    "inheritLocalOptionTwoFunction": {
       "kind": "function",
       "returnValue": {
         "type": "void",
@@ -104,19 +104,6 @@
       "remarks": [],
       "isBeta": false
     },
-    "inheritLocalOptionTwo": {
-      "kind": "enum",
-      "values": {},
-      "deprecatedMessage": [],
-      "summary": [
-        {
-          "kind": "textDocElement",
-          "value": "This is the summary for MyClass."
-        }
-      ],
-      "remarks": [],
-      "isBeta": false
-    },
     "IStructuredTypeInherit": {
       "kind": "interface",
       "extends": "",
diff --git a/api-extractor/testInputs/example3/folder/MyClass.ts b/api-extractor/testInputs/example3/folder/MyClass.ts
@@ -4,17 +4,11 @@
 export enum inheritLocalOptionOne {
 }
 
-/**
- * {@inheritdoc example3:MyClass }
- */
-export enum inheritLocalOptionTwo {
-}
-
 /** 
  * {@inheritdoc MyClass.methodWithTwoParams }
  */
 // (Error #1) methodWithTwoParams not a member of MyClass
-export function inheritLocalOptionThreeFunction(): void {
+export function inheritLocalOptionTwoFunction(): void {
 }
 
 /**
diff --git a/api-extractor/testInputs/example3/index.ts b/api-extractor/testInputs/example3/index.ts
@@ -5,8 +5,7 @@ declare const packageDescription: void;
 
 export {
     inheritLocalOptionOne,
-    inheritLocalOptionTwo,
-    inheritLocalOptionThreeFunction,
+    inheritLocalOptionTwoFunction,
     inheritEnumValues,
     sourceEnumValuesDoc,
     inheritLocalCircularDependencyOne,
