migrate aio to eslint as tslint has been deprecated, the migration is restricted to the aio app and
its e2e tests and does not include the other tools, for such reason both tslint and codelyzer have not
been removed (to be done in a next PR)
some minor tweaks needed to be applied to the code so that it would adhere to the new ESLinting behaviour
most TSLint rules have been substituted with their ESLint equivalent, with some exceptions:
* [whitespace] does not have an ESLint equivalent (suggested to be handled by prettier)
* [import-spacing] does not have an ESLint equivalent (suggested to be handled by prettier)
* [ban] replaced with [no-restricted-syntax] as there is no (official/included) ESLint equivalent
some rules have minor different behaviours compared to their TSLint counterparts:
* @typescript-eslint/naming-convention:
- typescript-eslint does not enforce uppercase for const only.
* @typescript-eslint/no-unused-expressions:
- The TSLint optional config "allow-new" is the default ESLint behavior and will no longer be ignored.
* arrow-body-style:
- ESLint will throw an error if the function body is multiline yet has a one-line return on it.
* eqeqeq:
- Option "smart" allows for comparing two literal values, evaluating the value of typeof and null comparisons.
* no-console:
- Custom console methods, if they exist, will no longer be allowed.
* no-invalid-this:
- Functions in methods will no longer be ignored.
* no-underscore-dangle:
- Leading and trailing underscores (_) on identifiers will now be ignored.
* prefer-arrow/prefer-arrow-functions:
- ESLint does not support allowing standalone function declarations.
- ESLint does not support allowing named functions defined with the function keyword.
* space-before-function-paren:
- Option "constructor" is not supported by ESLint.
- Option "method" is not supported by ESLint.
additional notes:
* the current typescript version used by the aio app is 4.3.5, which is not supported by typescript-eslint (the supported
versions are >=3.3.1 and <4.3.0). this causes a warning message to appear during linting, this issue should
likely/hopefully disappear in the future as typescript-eslint catches up
* The new "no-console" rule is not completely equivalent to what we had prior the migration, this is because TSLint's "no-console"
rule let you specify the methods you did not want to allow, whilst ESLint's "no-console" lets you specify the methods that you do
want to allow, so and in order not to have a very long list of methods in the ESLint rule it's been decided for the time being
to simply only allow the "log", "warn" and "error" methods
* 4 dependencies have been added as they have been considered necessary (see: https://github.com/angular/angular/pull/42820#discussion_r669978232)
extra:
* the migration has been performed by following: https://github.com/angular-eslint/angular-eslint#migrating-an-angular-cli-project-from-codelyzer-and-tslin
* more on typescript-eslint at: https://github.com/typescript-eslint/typescript-eslint
PR Close#42820
In #41788, the `disambiguateDocsPathsProcessor` was introduced to fix
an issue with case-insensitively equal paths. This processor may alter
the output paths of some docs. Due to its nature, the
`disambiguateDocPathsProcessor` must be the last processor in the
pipeline that updates a doc's output path. However, the
`updateGlobalApiPathProcess` (which also alters the output paths of some
docs) was not configured to run before `disambiguateDocPathsProcessor`.
As a result, the changes made by `disambiguateDocPathsProcessor` were
overridden by `updateGlobalApiPathProcess`, resulting in the app's
failing to load such global API docs pages. An example of such an API
page is: https://angular.io/api/core/global/ngApplyChanges
This commit fixes it by ensuring that the `updateGlobalApiPathProcess`
is explicitly run before the `disambiguateDocPathsProcessor`, so that
the former does not override the changes made by the latter.
PR Close#42648
This commit adds support for generating pages that document
special Angular elements, such as `ng-content` and `ng-template`,
which have special behavior in Angular but are not directives nor
components.
Resolves#41273
PR Close#41299
Such injectables were not appearing in the providers lists of their NgModule.
This commit updates the doc-gen to support associating these automatically.
Further, it also allows developers to mark other injectables that are provided
in an NgModule with a reference to the NgModule where they are provided.
The commit also does a refactoring of the `processNgModuleDocs` dgeni
processor code, to make it easier to maintain.
Fixes#41203
PR Close#41960
In 6cff877 we broke the decorator docs because the
doc-gen no longer knew how to identify them.
This commit updates the dgeni processor responsible
for identifying the decorators in the code and ensures
that the docs are now generated correctly.
Fixes#40851
PR Close#41091
`@angular/platform-server` provides the foundation for rendering an
Angular app on the server. In order to achieve that, it uses a
server-side DOM implementation (currently [domino][1]).
For rendering on the server to work as closely as possible to running
the app on the browser, we need to make DOM globals (such as `Element`,
`HTMLElement`, etc.), which are normally provided by the browser,
available as globals on the server as well.
Currently, `@angular/platform-server` achieves this by extending the
`global` object with the DOM implementation provided by `domino`. This
assignment happens in the [setDomTypes()][2] function, which is
[called in a `PLATFORM_INITIALIZER`][3]. While this works in most cases,
there are some scenarios where the DOM globals are needed sooner (i.e.
before initializing the platform). See, for example, #24551 and #39950
for more details on such issues.
This commit provides a way to solve this problem by exposing a
side-effect-ful entry-point (`@angular/platform-server/init`), that
shims the `global` object with DOM globals. People will be able to
import this entry-point in their server-rendered apps before
bootstrapping the app (for example, in their `main.server.ts` file).
(See also [#39950 (comment)][4].)
In a future update, the [`universal` schematics][5] will include such an
import by default in newly generated projects.
[1]: https://www.npmjs.com/package/domino
[2]: https://github.com/angular/angular/blob/0fc8466f1be392917e0c/packages/platform-server/src/domino_adapter.ts#L17-L21
[3]: https://github.com/angular/angular/blob/0fc8466f1be392917e0c/packages/platform-server/src/server.ts#L33
[4]: https://github.com/angular/angular/issues/39950#issuecomment-747598403
[5]: https://github.com/angular/angular-cli/blob/cc51432661eb4ab4b6a3/packages/schematics/angular/universal
PR Close#40559
Previously, if an entry-point had no public exports (such as the
`@angular/platform-server/shims` introduced in #40559, which is a
side-effect-ful entry-point), it was incorrectly marked as having all
its exports deprecated (which marks the entry-point as deprecated as
well).
This commit fixes this by ensuring that an entry-point is not marked as
having all its exports deprecated if it has no public exports.
PR Close#40737
This tag-def is being used in the `platform-server` source code,
and was causing warnings in the doc-gen. Adding support
prevents the warning from being shown.
Other than that this change has no effect on the generated
documentation, since the `@default` tag is not used in any
templates.
PR Close#40404
In the code base there are cases where there is, conceptually, a class
that is represented by a combination of an `interface`
(type declaration) and a `const` (value declaration).
For example:
```
export interface SomeClass {
count(a?: string): number;
}
export const: SomeClass = class {
someMethod(a: string = ''): number { ... }
};
```
These were being rendered as interfaces and also not
correctly showing the descriptions and default parameter
values.
In this commit such concepts are now rendered as classes.
The classes that are affected by this are:
* `DebugElement`
* `DebugNode`
* `Type`
* `EventEmitter`
* `TestBed`
Note that while decorators are also defined in this form
they have their own rendering type (`decorator`) and so
are not affecte by this.
PR Close#36989
Abstract directives cannot be part of a `@NgModule`, but the AIO dgeni
setup currently enforces this. This commit updates the logic so that
abstract directives are skipped.
PR Close#36921
Adds the ability to expose global symbols in the API docs via the `@globalApi` tag. Also supports optionally setting a namespace which will be added to the name automatically (e.g. `foo` will be renamed to `ng.foo`). Relevant APIs should also be exported through the `global.ts` file which will show up under `core/global`.
PR Close#34237
Injectable defs are not considered public API, so the property
that contains them should be prefixed with Angular's marker
for "private" ('ɵ') to discourage apps from relying on def
APIs directly.
This commit adds the prefix and shortens the name from
ngInjectableDef to "prov" (for "provider", since injector defs
are known as "inj"). This is because property names cannot
be minified by Uglify without turning on property mangling
(which most apps have turned off) and are thus size-sensitive.
PR Close#33151
Injector defs are not considered public API, so the property
that contains them should be prefixed with Angular's marker
for "private" ('ɵ') to discourage apps from relying on def
APIs directly.
This commit adds the prefix and shortens the name from
ngInjectorDef to inj. This is because property names
cannot be minified by Uglify without turning on property
mangling (which most apps have turned off) and are thus
size-sensitive.
PR Close#33151
`ng*Def` properties (such as `ngInjectorDef`) are not considered part of
the public API and should not appear in the API docs. This commit adds a
filter to remove these properties from the docs metadata.
PR Close#31378
This avoids warning such as the following ([example][1]):
```
warn: Invalid tags found -
doc "platform-browser/ɵBROWSER_SANITIZATION_PROVIDERS__POST_R3__" (const)
from file "platform-browser/src/browser.ts"
```
[1]: https://circleci.com/gh/angular/angular/427064
PR Close#32207
Adds two new helper functions that can be used when unit testing Angular services
that depend upon upgraded AngularJS services, or vice versa.
The functions return a module (AngularJS or NgModule) that is configured to wire up
the Angular and AngularJS injectors without the need to actually bootstrap a full
hybrid application.
This makes it simpler and faster to unit test services.
PR Close#16848
There is an encoding issue with using delta `Δ`, where the browser will attempt to detect the file encoding if the character set is not explicitly declared on a `<script/>` tag, and Chrome will find the `Δ` character and decide it is window-1252 encoding, which misinterprets the `Δ` character to be some other character that is not a valid JS identifier character
So back to the frog eyes we go.
```
__
/ɵɵ\
( -- ) - I am ineffable. I am forever.
_/ \_
/ \ / \
== == ==
```
PR Close#30546
The `Δ` caused issue with other infrastructure, and we are temporarily
changing it to `ɵɵ`.
This commit also patches ts_api_guardian_test and AIO to understand `ɵɵ`.
PR Close#29850
Now, one can add an `@alias` tag to API docs, which tells dgeni that this
API element (usually a `const`) is really just an alias for some API element
defined elsewhere.
Dgeni will then look up this API element and copy over the properties from
the alias to the current doc.
For example, we would like to privately export an Enum from `@angular/core`
but then publicly export this from `@angular/common`:
**packages/core/private_exports.ts**
```ts
/**
* Description of this document.
*/
export enum ɵSomeEnum { ... }
```
**packages/common/public_api.ts**
```ts
import {ɵSomeEnum} from '@angular/core';
/**
* @alias core/ɵSomeEnum
*/
export const SomeEnum = ɵSomeEnum;
```
In the generated docs there will be a page for `common/SomeEnum`, which
will be rendered as an enum, rather than a const, showing the description
extracted from the `core/ɵSomeEnum`.
---
The implementation of this feature required some refactoring of the other
processing:
1. Previously `ɵ` prefixed exports were not even considered.
2. Due to 1. some processors needed to have guards added to ignore such
private exports (`addMetadataAliases` and `checkContentRules`).
3. The processing of package pages had to be reworked (and split) so that
it picked up the aliased export docs after their alias proeprties had
been copied.
See FW-1207, FW-632, #29249
PR Close#29673
Currently our plan is to skip the publish, docgen, and update steps for this package.
During RC, we'll determine if the breaking change is too difficult for users, in which case we might restore the package for another major.
PR Close#29550
This commit includes the following changes:
* CLI version information is read from the CLI package from which
we read the help files.
* CLI API pages now contain GH links
* line numbers are not shown in GH links, if the doc does not
have a truthy `startingLine` value. This allows us to remove
hard coded checks for `guide` pages
* content pages and CLI api docs no longer have a `startingLine`
* the hard-coded `packages` path segment has been removed from
the templates; instead we now only use the `realProjectRelativePath`.
* the `realProjectRelativePath` has been updated accordingly for API
and CLI API docs.
PR Close#26515
If the documentation contains a `@selectors` tag then the content of that
is used to describe the selectors of a directive.
Otherwise the selector string is split and each selector is listed as
a list item in an unordered list.
PR Close#25768
The default dgeni config is to concatenate leading comments in front of API items.
In the case that you have an API item that starts a file with no import statements,
the license comment at the top of the file was being added to the front of the
API item's comment. SInce the license comment includes the `@license` tag
and the API item's comment did not start with `@description` the content of
the API item's comment was being put inside the `@license` tag, and no
description was being extracted from the API item's comment.
This commit updates to a version of dgeni-packages that has a switch to turn off
this concatenation, and then also configures this switch.
Closes#26045
PR Close#26050
All directives and pipes must now be tagged with one ore more
public NgModule, from which they are exported.
If an item is exported transitively via a re-exported internal NgModule
then it may be that the item appears to be exported from more than
one public NgModule. For example, there are shared directives that
are exported in this way from `FormsModule` and `ReactiveFormsModule`.
The doc-gen will error and fail if a directive or pipe is not tagged correctly.
NgModule pages now list all the directives and pipes that are exported from it.
Directive and Pipe pages now list any NgModule from which they are exported.
Packages also now list any NgModules that are contained - previously they were
missed.
PR Close#25734
dario-piotrowicz
George Kalpakas
Pete Bacon Darwin
twerske
Joey Perrott
Sonu Kapoor
Paul Gschwendtner
crisbeto
Kara Erickson
Ben Lesh
Brandon
Alex Rickabaugh
Alex Eagle
Adam Plumer