Files which export only enums not properly handled

[bastijnv]

type2docfx does not properly handle files that only export enums. A file is generated with as child the the enum but no references. DocFX build fails on these files.

To reproduce you can extract the AuthenticationType from authentication_provide.ts in a separate file and change authentication_provide.ts to the following:

// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

import { TransportConfig } from './authorization';
import { Callback } from './promise_utils';
import { AuthenticationType } from './authentication_type'

/**
 * Interface that must be implemented by objects that are used to provide credentials to the transports used by the device client
 * to authenticate with an Azure IoT hub instance.
 */
export interface AuthenticationProvider {
  type: AuthenticationType;
  getDeviceCredentials(callback: Callback<TransportConfig>): void;
  getDeviceCredentials(): Promise<TransportConfig>;
  setTokenRenewalValues?(tokenValidTimeInSeconds: number, tokenRenewalMarginInSeconds: number): void;
  }

Now run:

1. typedoc --json api.json azure-iot-sdk-node/common/core/src --module commonjs --includeDeclarations --ignoreCompilerErrors --excludeExternals
2. type2docfx api.json yml

This generates a yml file named authentication_type.yml which contains the following:

### YamlMime:UniversalReference
items:
  - uid: azure-iot-common.authentication_type
    name: authentication_type
    langs:
      - typeScript
    fullName: authentication_type
    children:
      - azure-iot-common.authentication_type.AuthenticationType
    type: module
    summary: ''
    package: azure-iot-common
references: []

If you use that as the YML input to DocFX (docfx docfx.json --serve) you will get the following error during build:

[20-03-31 07:37:29.731]Error:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.UniversalReferenceDocumentProcessor.Save](yml/authentication_type.yml)Can't find azure-iot-common.authentication_type.AuthenticationType in items or references
[20-03-31 07:37:36.069]Info:[BuildCommand]Completed building documents in 11749.1673 milliseconds.
[20-03-31 07:37:36.073]Info:[BuildCommand]Completed Scope:BuildCommand in 12034.604 milliseconds.
[20-03-31 07:37:36.074]Error:Can't find azure-iot-common.authentication_type.AuthenticationType in items or references

I think the solution is to simply not generate the file authentication_type.yml as it is not required.

[bastijnv]

Testing with removing the file altogether results in a non-clickable reference in the authentication_provider. Maybe it is best to accept the "enum" as top-level item:

export const setOfTopLevelItems = new Set(['class', 'interface', 'module', 'type alias', 'enum']);

This will correctly generate the file authentication_type.yml with the childs and references.

[qinezh]

Thank you @bastijnv for reporting this issue. Can you please share the version of type2docfx you're using?

[bastijnv]

Sorry for the late reply. Missed your reply in my inbox.

I'm on version 0.10.3 (latest). Note that I also cloned this repo to play around for a fix.

[qinezh]

@bastijnv can you please try typedoc v0.15.0 to generate the api.json and try it again?

[bastijnv]

I was already using TypeDoc 0.17.0-3 for their library mode. Since this is above v0.15.0 I assume that the issue is still occuring.

Let me know if you want me to downgrade to v0.15.0 to try.

[qinezh]

@bastijnv Yeah, it would be great if you can downgrade to v0.15.0 to have a try.

[bastijnv]

tested on v0.15.0 and latest official release v0.15.6. There the file authentication_type.yml is not generated. Only from v0.17.x the file seems to be generated (introducing the issue).

[davidjenkins]

I am having this issue also with TypeDoc 0.17.6, type2docfx 0.10.3, DocFX 2.52.0. The module YAML includes the enum(s) in the children collection, but not in the references collection or the items collection.

[qinezh]

Yes, looks there's something changed in latest version of TypeDoc, and type2docfx need to be updated to support it.

[yunair]

latest TypeDoc seems to have solved this problem