Linting has recently been removed from the examples provided in angular.io
(see PRs #43592 and #43746) such removal effects the downloadable and
stackblitz examples but linting is still generally used in the examples
in the aio project itself (they are being migrated from tslint to eslint in
PR #43218) thus eslint directive comments are still necessary in the code itself.
So the comments need to be present but need not to be exposed to the users
(not in the zips, stackblitzes nor docs themselves), these changes are
removing such comments during the examples' parsing phase (effectively
removing them from all three sources mentioned above).
Original discussion: https://github.com/angular/angular/pull/43218#discussion_r697305494resolves#43788
PR Close#43831
This commit updates the necessary config settings to allow `.mjs` files to be able to be parsed by the region parser. We configure the parser to use `inline-c-only` so that comments are generated in like the below
```
// #docregion
```
rather than
```
/* #docregion */
```
PR Close#44027
This change makes docplaster markers fit better with the surrounding code
that is being rendered. Instead of:
```
{
"a": 100,
// ...
"b": 200,
// ...
}
```
you can now get
```
{
"a": 100,
// ...
"b": 200,
// ...
}
```
PR Close#43216
Now JSON files should be commented using
```
// #docregion
```
rather than
```
/* #docregion */
```
There are currently no JSON files with either kind of comments so this change
has no impact yet.
But when we add some examples with such comments, they will also benefit
from `// ... ` style docplasters to join docregion fragments.
PR Close#43216
We can define regions in our examples that can be referenced
and rendered in guides as code snippets. It is quite hard to ensure
that these regions are maintained correctly. One reason for this is
it is hard to know whether a region is being used or not.
This commit adds a new processor that checks for unused named
regions in examples and fails if any are found.
Fixes#19761
PR Close#40479
This commit updates the necessary config files to run the angular.io and
docs tooling unit tests in random order (and fixes the tests that were
failing due to their dependence on the previous ordered execution).
Besides being a good idea anyway, running tests in random order is the
new [default behavior in jasmine@3.0.0][1], so this commit is in
preparation of upgrading jasmine to the latest version.
[1]: https://github.com/jasmine/jasmine/blob/v3.0.0/release_notes/3.0.md#breaking-changes
PR Close#31527
Since #26396, the `title` property is ignored and `header` should be
used instead for specifying a code snippet's header.
This commit ensures that we don't accidentally set `title` have it be
silently ignored.
PR Close#26514
The `exampleMap` needs to hold an hash object for each
of the `collectExamples.exampleFolders` paths.
Previously these hash objects were only created if there
was actually an example file the hash's respective
example folder. This could cause crashes during
`yarn docs-watch` (and so also `yarn sync-and-serve`)
if no examples were read in for a particular run of
the doc-gen.
PR Close#22502
By setting `renderExamples.ignoreBrokenExamples = true` the doc-gen will
not fail if there is something wrong with an example. Instead it will
just log a warning.
