Commit Graph

93 Commits

Author SHA1 Message Date
Kristiyan Kostadinov e7cf1e0580 feat(docs-infra): add the ability to expose globals (#34237)
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
2019-12-06 10:58:09 -08:00
Kara Erickson 86104b82b8 refactor(core): rename ngInjectableDef to ɵprov (#33151)
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
2019-10-16 16:36:19 -04:00
Kara Erickson cda9248b33 refactor(core): rename ngInjectorDef to ɵinj (#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
2019-10-16 16:36:19 -04:00
George Kalpakas 9364a14d36 fix(docs-infra): ignore `ng*Def` members in API docs (#31378)
`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
2019-10-03 10:24:34 -07:00
George Kalpakas 3e52e32dce build(docs-infra): add empty `codeGenApi` JSDoc tag definition (#32207)
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
2019-08-28 09:41:21 -07:00
Pete Bacon Darwin 3fb78aaacc feat(upgrade): provide unit test helpers for wiring up injectors (#16848)
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
2019-06-20 17:04:01 -07:00
Ben Lesh d7eaae6f22 refactor(ivy): Move instructions back to ɵɵ (#30546)
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
2019-05-20 16:37:47 -07:00
Brandon 6cb3b50a03 docs(docs-infra): add common/upgrade to API package sources (#30331)
Closes #30332

PR Close #30331
2019-05-16 11:47:16 -07:00
Ben Lesh cf86ed7b29 refactor(ivy): migrate ɵɵ prefix back to Δ (#30362)
Now that issues are resolved with Closure compiler, we can move back to our desired prefix of `Δ`.

PR Close #30362
2019-05-14 16:52:15 -07:00
Alex Rickabaugh b0578061ce refactor(ivy): use ɵɵ instead of Δ for now (#29850)
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
2019-04-11 16:27:56 -07:00
Ben Lesh 138ca5a246 refactor(ivy): prefix all generated instructions (#29692)
- Updates all instructions to be prefixed with the Greek delta symbol

PR Close #29692
2019-04-10 12:11:40 -07:00
Pete Bacon Darwin a4f3f3f81d build(docs-infra): support doc aliases via `@alias` dgeni tag (#29673)
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
2019-04-04 10:52:36 -07:00
Pete Bacon Darwin 6233cd55f7 style(docs-infra): fix typo (#29673)
PR Close #29673
2019-04-04 10:52:36 -07:00
Alex Eagle 03d914a6c2 build: hide @angular/http for Angular v8 (#29550)
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
2019-04-02 10:55:31 -07:00
Adam Plumer 6b6fdffc12 fixup! docs: update Universal guide (#28296)
PR Close #28296
2019-03-11 10:52:18 -07:00
Adam Plumer a29ce57732 docs: migrate examples from @angular/http to @angular/common/http (#28296)
PR Close #28296
2019-03-11 10:52:17 -07:00
Pete Bacon Darwin 4bd9f53e8f feat(docs-infra): rename tagdef: `@experimental` to `@publicApi` (#26595)
PR Close #26595
2018-10-19 14:35:52 -07:00
Pete Bacon Darwin 4c0ad5238e build(docs-infra): display github links in CLI API docs (#26515)
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
2018-10-19 11:12:54 -07:00
Pete Bacon Darwin 9889276b15 build(docs-infra): directive inputs and outputs (#25768)
PR Close #25768
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin 46729c76a0 build(docs-infra): improve directive selector rendering (#25768)
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
2018-10-01 09:36:33 -07:00
Pete Bacon Darwin f22deb2e2d build(docs-infra): improve directive API doc templates (#25768)
Closes #22790
Closes #25530

PR Close #25768
2018-10-01 09:36:32 -07:00
Pete Bacon Darwin b8422b41bb build(docs-infra): fail doc-gen if a content rule fails (#26039)
PR Close #26039
2018-09-24 09:11:02 -07:00
Pete Bacon Darwin 8ac4dd6447 build(docs-infra): allow usage notes on decorator option properties (#26039)
PR Close #26039
2018-09-24 09:11:02 -07:00
Pete Bacon Darwin 3808416479 build(docs-infra): remove legacy jsdoc tag processing (#26039)
PR Close #26039
2018-09-24 09:11:02 -07:00
Pete Bacon Darwin cee7448efc build(docs-infra): add @nocollapse tag-def to prevent warning (#26039)
See https://github.com/angular/angular/blob/master/packages/compiler-cli/src/transformers/nocollapse_hack.ts

PR Close #26039
2018-09-24 09:11:02 -07:00
Pete Bacon Darwin 7f1cace2a2 build(docs-infra): sort NgModule exports by id (#26051)
PR Close #26051
2018-09-21 17:00:03 -07:00
Pete Bacon Darwin 56c86c7e79 build(docs-infra): sort package exports by id (#26051)
Closes #26046

PR Close #26051
2018-09-21 17:00:03 -07:00
Pete Bacon Darwin 026b60cd70 build(docs-infra): expose deprecated status on items more clearly (#25750)
PR Close #25750
2018-09-21 10:26:48 -07:00
Pete Bacon Darwin 9931bd7576 build(docs-infra): do not include license comment in first API doc (#26050)
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
2018-09-21 10:25:41 -07:00
Pete Bacon Darwin b94436d86c build(docs-infra): process and render ngmodule exports (#25734)
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
2018-09-19 16:18:24 -07:00
Pete Bacon Darwin bc5cb8153e build(docs-infra): separate NgModules from Classes in API docs (#25734)
PR Close #25734
2018-09-19 16:18:24 -07:00
Pete Bacon Darwin 4e45f2c481 build(docs-infra): include packages in API template breadcrumbs (#25453)
PR Close #25453
2018-08-14 13:17:15 -07:00
Pete Bacon Darwin d8c828c9b1 build(docs-infra): implement the 'package' API template (#24631)
PR Close #24631
2018-07-13 19:45:54 -04:00
Pete Bacon Darwin cf0968f98e build(docs-infra): support hiding constructors of injectable classes (#24529)
Classes that are injectable often have constructors that should not be
called by the application developer. It is the responsibility of the
injector to instantiate the class and the constructor often contains
private implementation details that may need to change.

This commit removes constructors from the docs for API items that are
both:

a) Marked with an injectable decorator (e.g. Injectable, Directive,
Component, Pipe), and
b) Have no constructor description

This second rule allows the developer to override the removal if there
is something useful to say about the constructor.

Note that "normal" classes such as `angimations/HttpHeaders` do not have
their constructor removed, despite (at this time) having no description.

PR Close #24529
2018-06-26 10:58:11 -07:00
Pete Bacon Darwin 8daadf360c build(aio): compute breadcrums for all API doc types (#24000)
PR Close #24000
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin bc4f10ca20 build(aio): rearrange processors to ensure we catch all content errors (#24000)
PR Close #24000
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin d4d8125b2d build(aio): refactor the decorator doc processing (#24000)
PR Close #24000
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 62443b04a0 build(aio): do not allow `@usageNotes` on properties (#24000)
PR Close #24000
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 4168c946c6 build(aio): add content rule to prevent usageNotes in non-export API docs (#24000)
This commit also factors out `API_CONTAINED_DOC_TYPES` to be used by
both `filterContainedDocs` and `addAllowedPropertiesRules`.

PR Close #24000
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 5fb0b567ce build(aio): don't render `@Annotation` tags (#24000)
Because we were "ignoring" these tags they were being
rendered as part of the previous tag.
What we really want to do is know about them, so that we
don't break the doc-gen but then ignore them when rendering.

PR Close #24000
2018-06-13 16:47:40 -07:00
Pete Bacon Darwin 9f877f4416 build(docs-infra): ensure stability is computed before the API list (#24356)
Previously the API list was being generated before the stability had
been computed. This meant that the API list page showed no API docs
when filtering by `stable` stability status.

Closes #24329

PR Close #24356
2018-06-08 13:33:32 -07:00
Pete Bacon Darwin 68d37ef0c1 build(aio): ensure the correct decorator properties are merged (#24289)
Previously only the `description` and `usageNotes` were being copied over
from the call-member of the decorator interface. Important properties such
as `shortDescription` were missed.

These are now added and the code has been refactored to make it simpler and
clearer to update which properties get copied as the requirements change.

PR Close #24289
2018-06-06 10:23:47 -07:00
Pete Bacon Darwin a2e8b3a6a8 build(aio): ensure usageNotes are copied into decorator API docs (#23901)
PR Close #23901
2018-05-14 10:35:33 -07:00
Pete Bacon Darwin aae437cb1e build(aio): implement rules to prevent short parameter names (#22759)
PR Close #22759
2018-04-12 00:06:49 -07:00
Pete Bacon Darwin fa11d7822c build(aio): create minLength content rule (#22759)
This rule can be used to ensure that properties contain a minimum
number of characters.

PR Close #22759
2018-04-12 00:06:49 -07:00
Pete Bacon Darwin 1619160c8a build(aio): implement rules to prevent headings in content (#22759)
* No headings are allowed in `description` and `shortDescription`
* Only heading level 3 is allowed in `usageNotes`

PR Close #22759
2018-04-12 00:06:49 -07:00
Pete Bacon Darwin 7a8c58162c build(aio): create noMarkdownHeadings content rule (#22759)
This content rule can check what markdown headings
appear in content properties.

PR Close #22759
2018-04-12 00:06:49 -07:00
Veres Lajos de90314304 style: typos fixed - https://github.com/vlajos/misspell-fixer (#22975)
PR Close #22975
2018-03-27 14:51:53 -04:00
Andrew Seguin 22b96b9690 feat(elements): add support for creating custom elements (#22413)
PR Close #22413
2018-03-16 12:39:07 -07:00
Pete Bacon Darwin 19e6b8dad5 build(aio): fix `addNotYetDocumentedProperty` processor (#22770)
It was running too late and so was being confused by the
description being split into `shortDescription` and `description`
properties.

Closes #22748

PR Close #22770
2018-03-15 11:37:31 -07:00