Declaration files do not retain JSDoc comments

[brandongregoryscott]

After publish, the JSDoc comments are not retained in neither the typescript declaration files or transpiled javascript. The reason being this line:
https://github.com/AndcultureCode/AndcultureCode.JavaScript.React/blob/c5d923dc395e1fcc1943ac12f91e03f5194bc9a7/tsconfig.json#L18

This is a known issue, but there still isn't a solution that allows for removing comments but still keeping the JSDoc comments. See here: microsoft/TypeScript#14619

The simplest solution for the time being is to set "removeComments": false

Similar to rsm-hcd/AndcultureCode.JavaScript.React#37

[brandongregoryscott]

Published with v0.2.0

[brandongregoryscott]

Reopening this issue - after further investigation, the removal of the "removeComments": false line (or setting it to true explicitly) in the tsconfig file was not enough. Narrowed down the issue for our utility classes due to the remapping of a private function to the exported object. If you move the JSDoc comment above that public member, it is retained.

CollectionUtils, for example:

// -----------------------------------------------------------------------------------------
// #region Exports
// -----------------------------------------------------------------------------------------

export const CollectionUtils = {
    difference: _difference,
    /**
     * Compare two collections by a property of each value,
     * specified by selector, not considering the order of
     * elements, as long as all elements of one exist in the
     * other.
     * @param selector a function taking the item of the array and returning a property.
     * @param array1 first array to compare.
     * @param array2 second array to compare.
     * @returns true if both arrays contain all the same elements of the other,
     *          not considering order, false otherwise.
     */
    equalsBy: _equalsBy,
    first: _head,
    flattenDeep: _flattenDeep,
    hasValues: _hasValues,
    isEmpty: _isEmpty,
    isNotEmpty: _isNotEmpty,
    intersection: _intersection,
    intersectionWith: _intersectionWith,
    length: _length,
    removeElementAt: _removeElementAt,
    replaceElementAt: _replaceElementAt,
    sample: _sample,
    sampleSize: _sampleSize,
    sortByString: _sortByString,
    take: _take,
};

// #endregion Exports

The generated collection-utils.d.ts file is:

import * as Immutable from "immutable";
export declare const CollectionUtils: {
    difference: <T>(array: T[] | null | undefined, ...values: T[][]) => T[];
    /**
     * Compare two collections by a property of each value,
     * specified by selector, not considering the order of
     * elements, as long as all elements of one exist in the
     * other.
     * @param selector a function taking the item of the array and returning a property.
     * @param array1 first array to compare.
     * @param array2 second array to compare.
     * @returns true if both arrays contain all the same elements of the other,
     *          not considering order, false otherwise.
     */
    equalsBy: <T_1, V>(selector: (element: T_1) => V, array1: T_1[] | Immutable.List<any> | undefined, array2: T_1[] | Immutable.List<any> | undefined) => boolean;
    first: <T_2>(array: T_2[] | null | undefined) => T_2 | undefined;
    flattenDeep: <T_3>(array: T_3[] | null | undefined) => T_3[];
    hasValues: (...collections: (any[] | Immutable.List<any> | undefined)[]) => boolean;
    isEmpty: (...collections: (any[] | Immutable.List<any> | undefined)[]) => boolean;
    isNotEmpty: (...collections: (any[] | Immutable.List<any> | undefined)[]) => boolean;
    intersection: <T_4>(...arrays: T_4[][]) => T_4[];
    intersectionWith: <T1, T2>(array: T1[], values: T2[], comparator: (a: T1, b: T2) => boolean) => T1[];
    length: (arr: any[] | Immutable.List<any>) => number;
    removeElementAt: <T_5>(source: T_5[], index: number) => T_5[];
    replaceElementAt: <T_6>(source: T_6[], index: number, value: T_6) => T_6[];
    sample: <T_7>(collection: T_7[] | null | undefined) => T_7 | undefined;
    sampleSize: <T_8>(collection: T_8[] | null | undefined, n?: number | undefined) => T_8[];
    sortByString: <T_9 extends any>(array: T_9[], selector: (element: T_9) => string, caseSensitive?: boolean) => T_9[];
    take: <T_10>(array: T_10[] | null | undefined, n?: number | undefined) => T_10[];
};

I think the simplest solution would be to directly export the functions, and kill the concept of a 'private' function in these utility classes, so we don't have to duplicate the comments, or have them all at the end of the file, which seems counter productive.

[dtnhinh]

This issue is worked on #69

[brandongregoryscott]

Reopening this. I am seeing the JSDoc comments in the generated JS, but not TS definition files 🤦‍♂️ It seems really nitpicky about where the functions are defined, and it is doing the 'private remapping' under the hood even though we are referencing the functions directly in the exported object..

core-utils.js

core-utils.d.ts

Attaching all of the functions directly to the CoreUtils object before it is exported seems to get the desired effect. I will take care of this (at least for CoreUtils and RecordUtils) in #83 which I am currently working on. Just circling back here since we've had a few different attempts at this.

This is what core-utils.ts looks like now -

core-utils.js

core-utils.d.ts