This enables us to show overloads of methods in the API overview. This
is useful for e.g. showing the various signatures of the signal input
function, or for signal-based queris.
There seems to be some issues with the length of the `InputFunction`
overloads. There is some line wrapping that doesn't make it _super_
readable but this is an unrelated problem to this change, but rather
a question of UI / API representation in the angular.io site.
PR Close#54053
Fix case of not wanted internal properties displayed in the documentation by adding if blocks in the concerned templates. So if the option is marked as internal the template won't create an entry in the documentation table for the concerned property of method
Fixes#52018
PR Close#52020
Add the deprecated-api-item class on decorator-overview option code if deprecated. Add deprecated label on decorator-overview short description if deprecated. Add Add deprecated label on decorator option table header if option is deprecated.
PR Close#52041
This adds the new block syntax to dgeni docs pipeline, mainly copying
the way that elements (`<ng-content>` etc.) work. Actual doc content is
just a placeholder for this PR.
PR Close#52123
Enables the new `@` block syntax by default by removing the `enabledBlockTypes` flags. There are still some internal flags that allow special use cases to opt out of the block syntax, like during XML parsing and when compiling older libraries (see #51979).
PR Close#51994
The experimental tag is part of the stability tags along with "deprecated". This commit updates some code to pick up experimental as well.
PR Close#51712
This reverts commit a1ca162fd6.
This commit causes failures in g3, because `@Annotation` is load-bearing for
tsickle's decorator downleveling transformation.
PR Close#50206
The developer preview link was previously prefixed with the Github URL for
Angular's repo. However, it's meant to go to a guide page on AIO itself.
This commit removes the link prefix.
PR Close#46225
This commit adds a tag processor for `@developerPreview`. Adding this tag to
an exported symbol or to a decorator parameter causes an API status tag to
be shown for the API which links to the Developer Preview documentation.
PR Close#46050
If there were 1 or 2 additional overloads on a free-standing function in the API the overloads were not being shown.
Also the type of overload parameters were not being escaped correctly.
PR Close#44090
Fix incorrect escape of special characters when rendering member heritage docs. Example: DefaultIterableDiffer docs incorrectly renders what this class implements - it does not fully display generic types of implemented interfaces.
PR Close#43956
In the API docs, concrete classes do not list the "implementation" overload on a method, since this is not strictly part of its API.
We recently fixed the rendering of interfaces to display all the overloads, since there is no "implementation" overload.
This commit also fixes the rendering of "pseudo-classes", which are a combination of an interface
and a constant.
Fixes#43001
PR Close#43734
In the API docs, concrete classes do not list the "implementation" overload on a method, since this is not strictly part of its API.
There is already a special case for abstract methods that do not have such an implementation overload.
But we were missing the case where the method was part of an interface. In interfaces none of the methods have implementation overloads.
Fixes#43001
PR Close#43614
Previously, deprecation notes for deprecated class/interface properties
were not shown in the API docs. This commit fixes it by ensuring that
deprecation notes are shown for properites (similar to how it works for
methods).
PR Close#43566
The HTML for the docs pages is generated by Dgeni based on some
[Nunjucks][1] templates.
Previously, these templates were set up in a way that introduced a lot
excess whitespace in the generated HTML, unnecessarily bloating the
corresponding JSON files that need to be downloaded in order to view a
certain docs page. This has been discussed in #28105 and was again
observed while investigating #43285.
This commit refactors some of the templates related to API docs (which
seem to be the most affected ones) to drastically reduce the amount of
excess whitespace. More specifically, the total size of all files in
`generated/docs/api/` was reduced from ~13MB to ~7MB.
Besides the reduced payload size for each API page, this change will
also reduce the amount of memory needed by the ServiceWorker to cache
the API pages that have been visited by a user.
NOTE:
The affected files are not eagerly downloaded when navigating to
angular.io. Instead, each file is downloaded individually, as soon as a
user visits the corresponding API docs page. Therefore, the impact of
this change will be relatively small for most users.
[1]: https://mozilla.github.io/nunjucks/
PR Close#43435
NOTE:
This [version][1] includes a breaking fix ([commit af59f343d][2]). More
specifically `github-slugger` will no longer trim the text of a heading
before generating an ID and (with whitespace converted to `-`) this
results in different heading IDs:
**Before:** `<h3> foo bar </h3>` --> `<h3 id="foo-bar">...`
**After:** `<h3> foo bar </h3>` --> `<h3 id="--foo-bar--">...`
The different IDs now break some of our anchor-links, becuase
`github-slugger` is used by [rehype-slug][3], which is in turn used by
our [autolinkHeadings][4] dgeni post-processor.
To avoid the issue with broken anchor links, we update the
`renderMethodDetail()` nunjucks macro to omit excess whitespace in
headings.
[1]: https://github.com/Flet/github-slugger/releases/tag/v1.4.0
[2]: af59f343dc
[3]: https://github.com/rehypejs/rehype-slug
[4]: 75a3c778b1/aio/tools/transforms/angular-base-package/post-processors/autolink-headings.js (L3)
PR Close#43435
improve the @usageNotes message by adding the word "is"
(outcome: "Further information is available in...", compared to
"Further information available in...")
PR Close#42888
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
The "Usage Notes" section is often at the bottom of a long page of content
which can make it difficult to discover. This commit adds a link at the
end of the "Description" if there is a "Usage Notes" section on the page.
This link should help the reader to discover that there is more information
available further down the page.
This is basically a marginal fix. The longer term fix should be to
consider what content goes in which sections and how they should
be laid out on the page.
See #40753
PR Close#40835
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
Previously, only the first layer of sub-classes were filtered to remove
private exports. But on recursing down further levels these were not
filtered out.
PR Close#40404
Decorator API pages list all their available options in an overview
table and also in a detailed view. Now the rendered syntax of each
option will show a `?` after the name if the option is not required.
This is inline with how class and interface members are rendered.
PR Close#39167
On API docs pages for Angular packages (e.g. https://angular.io/api/common), we show all primary and secondary entry-points. Following a link to one of the secondary entry-points (e.g. https://angular.io/api/common/http), navigates the docs page for the secondary entry-point, where it is incorrectly (and misleadingly) labelled as PACKAGE and not as an entry-point.
Implemented a new ENTRY-POINT label and add support for correctly differentiating between entry-points and packages.
Fixes#34081
PR Close#35427
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
- Change margin to the header so that the the label aligns with the header
- Make code in API pages pre-wrap so that you can see the actual text on the screen - helps with issue #27296
- Modified text to be title case in label API to be consistent with rest of app labels
- Removed unused table of contents SCSS file
- TOC SCSS file reorg cleanup
- Soften headers font-weight in API pages
- Make linenums ordered list inside code examples always show as numbers
PR Close#31013
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
In some overloads, the parameter type can be a large anonymous
object type.
This change displays such types as `object`. It is then up to the
documentation author to put more information about the type in the
method usage notes.
PR Close#24976
* Make individual overloads collapsible
* Show only the first overload expanded, rest collapsed
* Text changes to 'collapse all' once 'show all' is clicked
* Fix chevron/carrot rotation animation when overloads / overload item is expanded or collapsed
PR Close#24976
