devextreme-internal-tools 7.7.0 → 7.8.2

package/Readme.md

@@ -1,429 +1,429 @@
-# DevExtreme Internal Tools #
-
-![](https://github.com/DevExpress/devextreme-internal-tools/workflows/Tests/badge.svg?branch=releases/v7)
-
-This package contains tools used by the DevExtreme team for development.
-
-# Commands
-
-| Command                                                          | Description                                                                               |
-| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| [discover-declarations](#discover-declarations)                  | Runs discovering                                                                          |
-| [discover-ts-declarations](#discover-ts-declarations)            | Runs discovering for TS files only                                                        |
-| [generate-smd](#generate-smd)                                    | Generates the `StrongMetaData.json` file                                                  |
-| [generate-ng-smd](#generate-ng-smd)                              | Generates the `NGDataMeta.json` file                                                      |
-| [update-meta](#update-meta)                                      | Updates the `NGDataMeta.json` file                                                        |
-| [generate-ts-bundle](#generate-ts-bundle)                        | Bundles all `*.d.ts` files to a single file (e.g. `dx.all.d.ts`)                            |
-| [update-ts-bundle](#update-ts-bundle)                            | Bundles all `*.d.ts` files to a single file (e.g. `dx.all.d.ts`)                            |
-| [integration-data-generator](#integration-data-generator)        | Generates `integration-data.json` and `integration-data-model.json`                       |
-| [update-integration-meta](#update-integration-meta)              | Updates `integration-data.json` and `integration-data-model.json`                         |
-| [inject-descriptions](#inject-descriptions)                      | Runs the injector for all `*.d.ts` files that equal the search pattern.                   |
-| [inject-descriptions-to-bundle](#inject-descriptions-to-bundle)  | Runs the injector for the `dx.all.d.ts` file only                                         |
-| [update-topics](#update-topics)                                  | Updates the documentation                                                                 |
-| [generate-content-map](#generate-content-map)                    | Generates content maps necessary to run `WebSite.JS`. The actual content is not included. |
-| [update-links](#update-links)                                    | Updates links for the site. Logs are saved in the root directory.                         |
-
----
-
-
-## discover-declarations
-```
-dx-tools discover-declarations
-```
-| Arg          | Default                            | Description                               |
-| ------------ | ---------------------------------- | ----------------------------------------- |
-| `js-scripts` | *rootDir*\js                       | See [common arguments](#common-arguments) |
-| `artifacts`  | *rootDir*\artifacts\internal-tools | See [common arguments](#common-arguments) |
-| `docs-root`  | Optional parameter                 | See [common arguments](#common-arguments) |
-| `ignore-pattern` | null                           | See [common arguments](#common-arguments) |
-
-## discover-ts-declarations
-```
-dx-tools discover-ts-declarations
-```
-| Arg          | Default      | Description                               |
-| ------------ | ------------ | ----------------------------------------- |
-| `js-scripts` | *rootDir*\js | See [common arguments](#common-arguments) |
-| `ignore-pattern` | null     | See [common arguments](#common-arguments) |
-
-## generate-smd
-```
-dx-tools generate-smd --version xx_x
-```
-| Arg                 | Default                                                | Description                               |
-| ------------------- | ------------------------------------------------------ | ----------------------------------------- |
-| `version`           | xx_x                                                   | See [common arguments](#common-arguments) |
-| `output-path`       | *rootDir*\artifacts\internal-tools\StrongMetaData.json | See [common arguments](#common-arguments) |
-| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json   | See [common arguments](#common-arguments) |
-
-## generate-ng-smd
-```
-dx-tools generate-ng-smd --version xx_x
-```
-| Arg                 | Default                                              | Description                               |
-| ------------------- | ---------------------------------------------------- | ----------------------------------------- |
-| `version`           | xx_x                                                 | See [common arguments](#common-arguments) |
-| `output-path`       | *rootDir*\artifacts\internal-tools\NGMetaData.json   | See [common arguments](#common-arguments) |
-| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json | See [common arguments](#common-arguments) |
-
-## update-meta
-```
-dx-tools update-meta --version xx_x --js-scripts D:\DevExtreme\js --docs-root D:\devextreme-docs
-```
-| Arg                 | Default                                              | Descriptions                              |
-| ------------------- | ---------------------------------------------------- | ----------------------------------------- |
-| `version`           | xx_x                                                 | See [common arguments](#common-arguments) |
-| `js-scripts`        | *rootDir*\js                                         | See [common arguments](#common-arguments) |
-| `artifacts`         | *rootDir*\artifacts\internal-tools                   | See [common arguments](#common-arguments) |
-| `output-path`       | *rootDir*\artifacts\internal-tools\NGMetaData.json   | See [common arguments](#common-arguments) |
-| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json | See [common arguments](#common-arguments) |
-| `docs-root`         | Optional parameter                                   | See [common arguments](#common-arguments) |
-| `ignore-pattern`    | null                                                 | See [common arguments](#common-arguments) |
-
-## generate-ts-bundle
-```
-dx-tools generate-ts-bundle --js-scripts D:\DevExtreme\js --output-path D:\DevExtreme\ts\dx.all.d.ts
-```
-| Arg           | Default                  | Description                               |
-| ------------- | ------------------------ | ----------------------------------------- |
-| `js-scripts`  | undefined                | See [common arguments](#common-arguments) |
-| `output-path` | undefined                | See [common arguments](#common-arguments) |
-| `ignore-pattern` | null                  | See [common arguments](#common-arguments) |
-
-For more information, see [Bundler specs](#bundler-specs)
-
-## update-ts-bundle
-```
-dx-tools update-ts-bundle --js-scripts D:\DevExtreme\js --output-path D:\DevExtreme\ts\dx.all.d.ts
-```
-| Arg           | Default                  | Description                               |
-| ------------- | ------------------------ | ----------------------------------------- |
-| `js-scripts`  | undefined                | See [common arguments](#common-arguments) |
-| `output-path` | undefined                | See [common arguments](#common-arguments) |
-| `ignore-pattern` | null                  | See [common arguments](#common-arguments) |
-
-For more information, see [Bundler specs](#bundler-specs)
-
-## integration-data-generator
-```
-dx-tools integration-data-generator
-```
-| Arg                 | Default                                                  | Description                               |
-| ------------------- | -------------------------------------------------------- | ----------------------------------------- |
-| `output-path`       | *rootDir*\artifacts\internal-tools\integration-data.json | See [common arguments](#common-arguments) |
-| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json     | See [common arguments](#common-arguments) |
-
-## update-integration-meta
-```
-dx-tools update-integration-meta --js-scripts D:\DevExtreme\js --docs-root D:\devextreme-docs
-```
-| Arg                 | Default                                                  | Description                               |
-| ------------------- | -------------------------------------------------------- | ----------------------------------------- |
-| `js-scripts`        | *rootDir*\js                                             | See [common arguments](#common-arguments) |
-| `artifacts`         | *rootDir*\artifacts\internal-tools                       | See [common arguments](#common-arguments) |
-| `output-path`       | *rootDir*\artifacts\internal-tools\integration-data.json | See [common arguments](#common-arguments) |
-| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json     | See [common arguments](#common-arguments) |
-| `docs-root`         | Optional parameter                                       | See [common arguments](#common-arguments) |
-| `ignore-pattern`    | null                                                     | See [common arguments](#common-arguments) |
-
-## inject-descriptions
-```
-dx-tools inject-descriptions
-```
-| Arg                 | Default                                              | Description                               |
-| ------------------- | ---------------------------------------------------- | ----------------------------------------- |
-| `js-scripts`        | *rootDir*\js                                         | See [common arguments](#common-arguments) |
-| `descriptions-path` | *rootDir*\artifacts\internal-tools\Descriptions.json | Sets path to the Descriptions.json file   |
-| `search-pattern`    | *                                                    | Sets a pattern to find the files          |
-| `ignore-pattern`    | null                                                 | See [common arguments](#common-arguments) |
-
-## inject-descriptions-to-bundle
-```
-dx-tools inject-descriptions-to-bundle
-```
-| Arg                 | Default                                                          | Description                               |
-| ------------------- | ---------------------------------------------------------------- | ----------------------------------------- |
-| `js-scripts`        | *rootDir*\js                                                     | See [common arguments](#common-arguments) |
-| `descriptions-path` | *rootDir*\artifacts\internal-tools\Descriptions.json             | Sets path to the Descriptions.json file   |
-| `target-path`       | *rootDir*\node_modules\devextreme-internal-tools\bin\dx.all.d.ts | Sets the path to the `dx.all.d.ts` file   |
-| `output-path`       | `target-path                                                     | See [common arguments](#common-arguments) |
-| `ignore-pattern`    | null                                                             | See [common arguments](#common-arguments) |
-
-## update-topics
-```
-dx-tools update-topics
-```
-| Arg          | Default                            | Description                               |
-| ------------ | ---------------------------------- | ----------------------------------------- |
-| `js-scripts` | *rootDir*\js                       | See [common arguments](#common-arguments) |
-| `docs-root`  | *rootDir*                          | See [common arguments](#common-arguments) |
-| `artifacts`  | *rootDir*\artifacts\internal-tools | See [common arguments](#common-arguments) |
-
-## generate-content-map
-```
-dx-tools generate-content-map
-```
-| Arg         | Default                   | Description                               |
-| ----------- | ------------------------- | ----------------------------------------- |
-| `docs-root` | *rootDir*                 | See [common arguments](#common-arguments) |
-| `version`   | Version in `package.json` | See [common arguments](#common-arguments) |
-
-## update-links
-```
-dx-tools update-links --check-all --validation
-```
-| Flag               | Description                                  |
-| ------------------ | -------------------------------------------- |
-| `--fail-on-change` | Check and update links in changed files only |
-| `--check-all`      | Check and update links in all files          |
-| `--validation`     | Check links without updating them            |
-
-# Common Arguments
-
-| Arg                 | Description                                                                                         |
-| ------------------- | --------------------------------------------------------------------------------------------------- |
-| `js-scripts`        | Path to the `js` folder in the [DevExtreme repo](https://github.com/DevExpress/DevExtreme)          |
-| `docs-root`         | Path to the [devextreme-documentation repo](https://github.com/DevExpress/devextreme-documentation) |
-| `version`           | Major version (for example, `20_1`)                                                                 |
-| `artifacts`         | Path to the `artifacts` folder                                                                      |
-| `declarations-path` | Path to the `Declarations.json` file                                                                |
-| `output-path`       | Path to the output file                                                                             |
-| `ignore-pattern`    | Pattern for ignoring files                                                                          |
-
-
-# Development
-
-We assume that [DevExtreme repo](https://github.com/DevExpress/DevExtreme) is located in the same parent directory:
-```
-···
-├── devextreme/
-│   ├── js/
-│   └── ···
-├── devextreme-internal-tools/
-│   └── ···
-···
-```
-If you need to target another directory, go to `./package.json` and change `--js-scripts` argument value.
-
-## Discover TypeScript Declarations
-
-```
-npm run build-ts
-npm run discover
-```
-
-The commands above run the TypeScript Discoverer only. The .NET Discoverer should be run separately.
-
-## Discover TypeScript Declarations in Watch Mode
-
-```
-npm run build-ts-watch
-npm run discover-watch
-```
-
-`build-ts-watch` recompiles the TypeScript Discoverer when its sources change.
-
-`discover-watch` reruns the TypeScript Discoverer when Declarations change.
-
-# Additional Information
-
-## Bundler specs
-
-`Bundler` is a tool that bundles all `*.d.ts` files into a single `bundle` file. A `bundle` is a file with a set of module declarations (namespaces).
-
-```typescript
-declare global {}
-
-declare module DevExpress {}
-
-declare module DevExpress.module1 {}
-```
-
-The bundling process starts with collecting all `public` types (types, interfaces, classes, etc.). A type is considered `public` if it is:
-
-- exported and has the `@docid`, `@public`, or `@const` jsDoc tag.
-- referenced by another `public` type.
-
-```typescript
-
-export interface NonPublicType { }
-
-/** @docid */
-export interface PublicType {
-   field: AnotherPublicType;
-}
-
-export interface AnotherPublicType {}
-
-```
-
-The next step is to decide what namespace the `public` type belongs to.
-
-There are two options:
-
-- the namespace is set explicitly with the help of the `@namespace` jsDoc tag.
-- the namespace is calculated based on the type file location and structure.
-
-In the latter case, there are 3 options:
-
-- if the type is declared in the `global` namespace, it is preserved in this namespace.
-- the calculated namespace is a `DevExpress` string followed by the first folder name in `cwd`. E.g., for types in the `{cwd}/core/utils/math/calculation.utils.d.ts` file, the namespace is `DevExpress.core`.
-- if there is the default export of some class in the file, this class is considered a widget class, and then the `public` type is placed in the nested module with the name of the exported widget class. E.g., for types in the `{cwd}/ui/data_grid.d.ts` file with the `dxDataGrid` class as the default export, the module is `dxDataGrid` inside the `DevExpress.ui` namespace.
-
-In the last step, all jsDoc comments are transformed by the [Collapser](#collapser-specs).
-
-For example, consider the following files:
-
-```typescript
-// {cwd}/ui/some_widget.d.ts
-
-import { MyType } from '../core/utils';
-
-export type SimplePropType = number;
-
-/**
- * @public
- * @namespace DevExpress.ui.options
- */
-export interface WidgetOptions {
-    myProp?: MyType;
-}
-
-/** @public */
-export default class Widget {
-    getOptions(): WidgetOptions;
-    getSingleProp(): SimplePropType;
-}
-```
-
-```typescript
-// {cwd}/core/utils.d.ts
-
-export type MyType = string;
-
-export type MyType = string;
-
-export type MySuperType = any;
-```
-
-The result of bundling these files:
-
-```typescript
-declare module DevExpress.core {
-    /**
-     * @deprecated Attention! This type is for internal purposes only...
-     */
-    export type MyType = string;
-}
-
-declare module DevExpress.ui {
-    module Widget {
-        /**
-         * @deprecated Attention! This type is for internal purposes only...
-         */
-        export type SimplePropType = number;
-    }
-
-    /**
-     * [descr:Widget]
-     */
-    export class Widget {
-        getOptions(): DevExpress.ui.options.WidgetOptions;
-
-        getSingleProp(): DevExpress.ui.Widget.SimplePropType;
-    }
-}
-
-declare module DevExpress.ui.options {
-    /**
-     * [descr:WidgetOptions]
-     */
-    export interface WidgetOptions {
-        myProp?: DevExpress.core.MyType;
-    }
-}
-```
-
-To replace placeholders with actual descriptions or deprecation messages, use the [inject-descriptions-to-bundle](#inject-descriptions-to-bundle) command.
-
-
-## Collapser specs
-
-The collapser is an internal process that runs against `*.d.ts` files and simplifies jsDoc comments to prepare them for further usage. It is used by the [inject-descriptions](#inject-descriptions) command as a first step and by [update-ts-bundle](#update-ts-bundle) as a last step.
-
-The collapser changes jsDoc comments following the rules below:
-
-- the `@docid` or `@const` jsDoc tag is replaced with a placeholder for description.
-- the `@deprecated` tag with a custom (or empty) message is preserved.
-- the `@deprecated` tag with a reference to other types either by `docid` or `{file/path.typeName}` is preserved, but the reference is replaced with a placeholder for a correct deprecation message.
-- all other tags or content of a jsDoc comment will be removed.
-- if the original type has no `@public` tag or jsDoc comments, an additional `@deprecated` tag is added with a standard warning message stating that this type is for internal use.
-
-Once the collapser process is completed, all jsDoc comments will contain only placeholders and meaningful deprecation messages.
-
-Let's look at an example. Below is the initial file.
-
-```typescript
-/**
- * @docid
- * @public
- */
-export interface WidgetProps {}
-
-/**
- * @docid
- * @public
- * @deprecated WidgetProps
- */
-export interface WidgetOptions {}
-
-/**
- * @deprecated This is custom message
- * @public
- */
-export type DeprecatedType = {};
-
-/**
- * @docid
- * @public
- * @deprecated {file_path/file_name.TypeName}
- */
-export type OldType = {};
-
-export type InternalType = {};
-```
-
-And this is the result of the applied collapser:
-
-```typescript
-/**
- * [descr:WidgetProps]
- */
-export interface WidgetProps {}
-
-/**
- * [descr:WidgetOptions]
- * @deprecated [depNote:WidgetProps]
- */
-export interface WidgetOptions {}
-
-/**
- * @deprecated This is custom message
- */
-export type DeprecatedType = {};
-
-/**
- * [descr:OldType]
- * @deprecated [depNote.OldType]
- */
-export type OldType = {};
-
-/**
- * @deprecated Attention! This type is for internal purposes only...
- */
-export type InternalType = {};
-```
-
-# License
-
-**DevExtreme Internal Tools are released as MIT-licensed.**
+# DevExtreme Internal Tools #
+
+![](https://github.com/DevExpress/devextreme-internal-tools/workflows/Tests/badge.svg?branch=releases/v7)
+
+This package contains tools used by the DevExtreme team for development.
+
+# Commands
+
+| Command                                                          | Description                                                                               |
+| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [discover-declarations](#discover-declarations)                  | Runs discovering                                                                          |
+| [discover-ts-declarations](#discover-ts-declarations)            | Runs discovering for TS files only                                                        |
+| [generate-smd](#generate-smd)                                    | Generates the `StrongMetaData.json` file                                                  |
+| [generate-ng-smd](#generate-ng-smd)                              | Generates the `NGDataMeta.json` file                                                      |
+| [update-meta](#update-meta)                                      | Updates the `NGDataMeta.json` file                                                        |
+| [generate-ts-bundle](#generate-ts-bundle)                        | Bundles all `*.d.ts` files to a single file (e.g. `dx.all.d.ts`)                            |
+| [update-ts-bundle](#update-ts-bundle)                            | Bundles all `*.d.ts` files to a single file (e.g. `dx.all.d.ts`)                            |
+| [integration-data-generator](#integration-data-generator)        | Generates `integration-data.json` and `integration-data-model.json`                       |
+| [update-integration-meta](#update-integration-meta)              | Updates `integration-data.json` and `integration-data-model.json`                         |
+| [inject-descriptions](#inject-descriptions)                      | Runs the injector for all `*.d.ts` files that equal the search pattern.                   |
+| [inject-descriptions-to-bundle](#inject-descriptions-to-bundle)  | Runs the injector for the `dx.all.d.ts` file only                                         |
+| [update-topics](#update-topics)                                  | Updates the documentation                                                                 |
+| [generate-content-map](#generate-content-map)                    | Generates content maps necessary to run `WebSite.JS`. The actual content is not included. |
+| [update-links](#update-links)                                    | Updates links for the site. Logs are saved in the root directory.                         |
+
+---
+
+
+## discover-declarations
+```
+dx-tools discover-declarations
+```
+| Arg          | Default                            | Description                               |
+| ------------ | ---------------------------------- | ----------------------------------------- |
+| `js-scripts` | *rootDir*\js                       | See [common arguments](#common-arguments) |
+| `artifacts`  | *rootDir*\artifacts\internal-tools | See [common arguments](#common-arguments) |
+| `docs-root`  | Optional parameter                 | See [common arguments](#common-arguments) |
+| `ignore-pattern` | null                           | See [common arguments](#common-arguments) |
+
+## discover-ts-declarations
+```
+dx-tools discover-ts-declarations
+```
+| Arg          | Default      | Description                               |
+| ------------ | ------------ | ----------------------------------------- |
+| `js-scripts` | *rootDir*\js | See [common arguments](#common-arguments) |
+| `ignore-pattern` | null     | See [common arguments](#common-arguments) |
+
+## generate-smd
+```
+dx-tools generate-smd --version xx_x
+```
+| Arg                 | Default                                                | Description                               |
+| ------------------- | ------------------------------------------------------ | ----------------------------------------- |
+| `version`           | xx_x                                                   | See [common arguments](#common-arguments) |
+| `output-path`       | *rootDir*\artifacts\internal-tools\StrongMetaData.json | See [common arguments](#common-arguments) |
+| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json   | See [common arguments](#common-arguments) |
+
+## generate-ng-smd
+```
+dx-tools generate-ng-smd --version xx_x
+```
+| Arg                 | Default                                              | Description                               |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------- |
+| `version`           | xx_x                                                 | See [common arguments](#common-arguments) |
+| `output-path`       | *rootDir*\artifacts\internal-tools\NGMetaData.json   | See [common arguments](#common-arguments) |
+| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json | See [common arguments](#common-arguments) |
+
+## update-meta
+```
+dx-tools update-meta --version xx_x --js-scripts D:\DevExtreme\js --docs-root D:\devextreme-docs
+```
+| Arg                 | Default                                              | Descriptions                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------- |
+| `version`           | xx_x                                                 | See [common arguments](#common-arguments) |
+| `js-scripts`        | *rootDir*\js                                         | See [common arguments](#common-arguments) |
+| `artifacts`         | *rootDir*\artifacts\internal-tools                   | See [common arguments](#common-arguments) |
+| `output-path`       | *rootDir*\artifacts\internal-tools\NGMetaData.json   | See [common arguments](#common-arguments) |
+| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json | See [common arguments](#common-arguments) |
+| `docs-root`         | Optional parameter                                   | See [common arguments](#common-arguments) |
+| `ignore-pattern`    | null                                                 | See [common arguments](#common-arguments) |
+
+## generate-ts-bundle
+```
+dx-tools generate-ts-bundle --js-scripts D:\DevExtreme\js --output-path D:\DevExtreme\ts\dx.all.d.ts
+```
+| Arg           | Default                  | Description                               |
+| ------------- | ------------------------ | ----------------------------------------- |
+| `js-scripts`  | undefined                | See [common arguments](#common-arguments) |
+| `output-path` | undefined                | See [common arguments](#common-arguments) |
+| `ignore-pattern` | null                  | See [common arguments](#common-arguments) |
+
+For more information, see [Bundler specs](#bundler-specs)
+
+## update-ts-bundle
+```
+dx-tools update-ts-bundle --js-scripts D:\DevExtreme\js --output-path D:\DevExtreme\ts\dx.all.d.ts
+```
+| Arg           | Default                  | Description                               |
+| ------------- | ------------------------ | ----------------------------------------- |
+| `js-scripts`  | undefined                | See [common arguments](#common-arguments) |
+| `output-path` | undefined                | See [common arguments](#common-arguments) |
+| `ignore-pattern` | null                  | See [common arguments](#common-arguments) |
+
+For more information, see [Bundler specs](#bundler-specs)
+
+## integration-data-generator
+```
+dx-tools integration-data-generator
+```
+| Arg                 | Default                                                  | Description                               |
+| ------------------- | -------------------------------------------------------- | ----------------------------------------- |
+| `output-path`       | *rootDir*\artifacts\internal-tools\integration-data.json | See [common arguments](#common-arguments) |
+| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json     | See [common arguments](#common-arguments) |
+
+## update-integration-meta
+```
+dx-tools update-integration-meta --js-scripts D:\DevExtreme\js --docs-root D:\devextreme-docs
+```
+| Arg                 | Default                                                  | Description                               |
+| ------------------- | -------------------------------------------------------- | ----------------------------------------- |
+| `js-scripts`        | *rootDir*\js                                             | See [common arguments](#common-arguments) |
+| `artifacts`         | *rootDir*\artifacts\internal-tools                       | See [common arguments](#common-arguments) |
+| `output-path`       | *rootDir*\artifacts\internal-tools\integration-data.json | See [common arguments](#common-arguments) |
+| `declarations-path` | *rootDir*\artifacts\internal-tools\Declarations.json     | See [common arguments](#common-arguments) |
+| `docs-root`         | Optional parameter                                       | See [common arguments](#common-arguments) |
+| `ignore-pattern`    | null                                                     | See [common arguments](#common-arguments) |
+
+## inject-descriptions
+```
+dx-tools inject-descriptions
+```
+| Arg                 | Default                                              | Description                               |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------- |
+| `js-scripts`        | *rootDir*\js                                         | See [common arguments](#common-arguments) |
+| `descriptions-path` | *rootDir*\artifacts\internal-tools\Descriptions.json | Sets path to the Descriptions.json file   |
+| `search-pattern`    | *                                                    | Sets a pattern to find the files          |
+| `ignore-pattern`    | null                                                 | See [common arguments](#common-arguments) |
+
+## inject-descriptions-to-bundle
+```
+dx-tools inject-descriptions-to-bundle
+```
+| Arg                 | Default                                                          | Description                               |
+| ------------------- | ---------------------------------------------------------------- | ----------------------------------------- |
+| `js-scripts`        | *rootDir*\js                                                     | See [common arguments](#common-arguments) |
+| `descriptions-path` | *rootDir*\artifacts\internal-tools\Descriptions.json             | Sets path to the Descriptions.json file   |
+| `target-path`       | *rootDir*\node_modules\devextreme-internal-tools\bin\dx.all.d.ts | Sets the path to the `dx.all.d.ts` file   |
+| `output-path`       | `target-path                                                     | See [common arguments](#common-arguments) |
+| `ignore-pattern`    | null                                                             | See [common arguments](#common-arguments) |
+
+## update-topics
+```
+dx-tools update-topics
+```
+| Arg          | Default                            | Description                               |
+| ------------ | ---------------------------------- | ----------------------------------------- |
+| `js-scripts` | *rootDir*\js                       | See [common arguments](#common-arguments) |
+| `docs-root`  | *rootDir*                          | See [common arguments](#common-arguments) |
+| `artifacts`  | *rootDir*\artifacts\internal-tools | See [common arguments](#common-arguments) |
+
+## generate-content-map
+```
+dx-tools generate-content-map
+```
+| Arg         | Default                   | Description                               |
+| ----------- | ------------------------- | ----------------------------------------- |
+| `docs-root` | *rootDir*                 | See [common arguments](#common-arguments) |
+| `version`   | Version in `package.json` | See [common arguments](#common-arguments) |
+
+## update-links
+```
+dx-tools update-links --check-all --validation
+```
+| Flag               | Description                                  |
+| ------------------ | -------------------------------------------- |
+| `--fail-on-change` | Check and update links in changed files only |
+| `--check-all`      | Check and update links in all files          |
+| `--validation`     | Check links without updating them            |
+
+# Common Arguments
+
+| Arg                 | Description                                                                                         |
+| ------------------- | --------------------------------------------------------------------------------------------------- |
+| `js-scripts`        | Path to the `js` folder in the [DevExtreme repo](https://github.com/DevExpress/DevExtreme)          |
+| `docs-root`         | Path to the [devextreme-documentation repo](https://github.com/DevExpress/devextreme-documentation) |
+| `version`           | Major version (for example, `20_1`)                                                                 |
+| `artifacts`         | Path to the `artifacts` folder                                                                      |
+| `declarations-path` | Path to the `Declarations.json` file                                                                |
+| `output-path`       | Path to the output file                                                                             |
+| `ignore-pattern`    | Pattern for ignoring files                                                                          |
+
+
+# Development
+
+We assume that [DevExtreme repo](https://github.com/DevExpress/DevExtreme) is located in the same parent directory:
+```
+···
+├── devextreme/
+│   ├── js/
+│   └── ···
+├── devextreme-internal-tools/
+│   └── ···
+···
+```
+If you need to target another directory, go to `./package.json` and change `--js-scripts` argument value.
+
+## Discover TypeScript Declarations
+
+```
+npm run build-ts
+npm run discover
+```
+
+The commands above run the TypeScript Discoverer only. The .NET Discoverer should be run separately.
+
+## Discover TypeScript Declarations in Watch Mode
+
+```
+npm run build-ts-watch
+npm run discover-watch
+```
+
+`build-ts-watch` recompiles the TypeScript Discoverer when its sources change.
+
+`discover-watch` reruns the TypeScript Discoverer when Declarations change.
+
+# Additional Information
+
+## Bundler specs
+
+`Bundler` is a tool that bundles all `*.d.ts` files into a single `bundle` file. A `bundle` is a file with a set of module declarations (namespaces).
+
+```typescript
+declare global {}
+
+declare module DevExpress {}
+
+declare module DevExpress.module1 {}
+```
+
+The bundling process starts with collecting all `public` types (types, interfaces, classes, etc.). A type is considered `public` if it is:
+
+- exported and has the `@docid`, `@public`, or `@const` jsDoc tag.
+- referenced by another `public` type.
+
+```typescript
+
+export interface NonPublicType { }
+
+/** @docid */
+export interface PublicType {
+   field: AnotherPublicType;
+}
+
+export interface AnotherPublicType {}
+
+```
+
+The next step is to decide what namespace the `public` type belongs to.
+
+There are two options:
+
+- the namespace is set explicitly with the help of the `@namespace` jsDoc tag.
+- the namespace is calculated based on the type file location and structure.
+
+In the latter case, there are 3 options:
+
+- if the type is declared in the `global` namespace, it is preserved in this namespace.
+- the calculated namespace is a `DevExpress` string followed by the first folder name in `cwd`. E.g., for types in the `{cwd}/core/utils/math/calculation.utils.d.ts` file, the namespace is `DevExpress.core`.
+- if there is the default export of some class in the file, this class is considered a widget class, and then the `public` type is placed in the nested module with the name of the exported widget class. E.g., for types in the `{cwd}/ui/data_grid.d.ts` file with the `dxDataGrid` class as the default export, the module is `dxDataGrid` inside the `DevExpress.ui` namespace.
+
+In the last step, all jsDoc comments are transformed by the [Collapser](#collapser-specs).
+
+For example, consider the following files:
+
+```typescript
+// {cwd}/ui/some_widget.d.ts
+
+import { MyType } from '../core/utils';
+
+export type SimplePropType = number;
+
+/**
+ * @public
+ * @namespace DevExpress.ui.options
+ */
+export interface WidgetOptions {
+    myProp?: MyType;
+}
+
+/** @public */
+export default class Widget {
+    getOptions(): WidgetOptions;
+    getSingleProp(): SimplePropType;
+}
+```
+
+```typescript
+// {cwd}/core/utils.d.ts
+
+export type MyType = string;
+
+export type MyType = string;
+
+export type MySuperType = any;
+```
+
+The result of bundling these files:
+
+```typescript
+declare module DevExpress.core {
+    /**
+     * @deprecated Attention! This type is for internal purposes only...
+     */
+    export type MyType = string;
+}
+
+declare module DevExpress.ui {
+    module Widget {
+        /**
+         * @deprecated Attention! This type is for internal purposes only...
+         */
+        export type SimplePropType = number;
+    }
+
+    /**
+     * [descr:Widget]
+     */
+    export class Widget {
+        getOptions(): DevExpress.ui.options.WidgetOptions;
+
+        getSingleProp(): DevExpress.ui.Widget.SimplePropType;
+    }
+}
+
+declare module DevExpress.ui.options {
+    /**
+     * [descr:WidgetOptions]
+     */
+    export interface WidgetOptions {
+        myProp?: DevExpress.core.MyType;
+    }
+}
+```
+
+To replace placeholders with actual descriptions or deprecation messages, use the [inject-descriptions-to-bundle](#inject-descriptions-to-bundle) command.
+
+
+## Collapser specs
+
+The collapser is an internal process that runs against `*.d.ts` files and simplifies jsDoc comments to prepare them for further usage. It is used by the [inject-descriptions](#inject-descriptions) command as a first step and by [update-ts-bundle](#update-ts-bundle) as a last step.
+
+The collapser changes jsDoc comments following the rules below:
+
+- the `@docid` or `@const` jsDoc tag is replaced with a placeholder for description.
+- the `@deprecated` tag with a custom (or empty) message is preserved.
+- the `@deprecated` tag with a reference to other types either by `docid` or `{file/path.typeName}` is preserved, but the reference is replaced with a placeholder for a correct deprecation message.
+- all other tags or content of a jsDoc comment will be removed.
+- if the original type has no `@public` tag or jsDoc comments, an additional `@deprecated` tag is added with a standard warning message stating that this type is for internal use.
+
+Once the collapser process is completed, all jsDoc comments will contain only placeholders and meaningful deprecation messages.
+
+Let's look at an example. Below is the initial file.
+
+```typescript
+/**
+ * @docid
+ * @public
+ */
+export interface WidgetProps {}
+
+/**
+ * @docid
+ * @public
+ * @deprecated WidgetProps
+ */
+export interface WidgetOptions {}
+
+/**
+ * @deprecated This is custom message
+ * @public
+ */
+export type DeprecatedType = {};
+
+/**
+ * @docid
+ * @public
+ * @deprecated {file_path/file_name.TypeName}
+ */
+export type OldType = {};
+
+export type InternalType = {};
+```
+
+And this is the result of the applied collapser:
+
+```typescript
+/**
+ * [descr:WidgetProps]
+ */
+export interface WidgetProps {}
+
+/**
+ * [descr:WidgetOptions]
+ * @deprecated [depNote:WidgetProps]
+ */
+export interface WidgetOptions {}
+
+/**
+ * @deprecated This is custom message
+ */
+export type DeprecatedType = {};
+
+/**
+ * [descr:OldType]
+ * @deprecated [depNote.OldType]
+ */
+export type OldType = {};
+
+/**
+ * @deprecated Attention! This type is for internal purposes only...
+ */
+export type InternalType = {};
+```
+
+# License
+
+**DevExtreme Internal Tools are released as MIT-licensed.**