honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix(docs-infra): always default to no linenums in `<aio-code>` (#31674) 

Previously, `linenums` defaulted to true if the content was more than 10
lines long and false otherwise.

Since in most cases linenums add unnecessary visual noise, this commit
changes `linenums` to always default to false (regardless of the size of
the content). It can be still be turned on by explicitly setting to true
or a number.

PR Close #31674
This commit is contained in:
George Kalpakas 2019-07-20 20:31:30 +03:00 committed by Miško Hevery
parent 3d7303efc0
commit dd0be7feb7
4 changed files with 47 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
aio/content/guide/docs-style-guide.md
View File

@ -428,7 +428,7 @@ You control the _code-example_ output by setting one or more of its attributes:
* `region`- displays the source file fragment with that region name; regions are identified by _docregion_ markup in the source file, as explained [below](#region "Displaying a code fragment").
* `linenums`- value may be `true`, `false`, or a `number`. When not specified, line numbers are automatically displayed when there are greater than 10 lines of code. The rarely used `number` option starts line numbering at the given value. `linenums=4` sets the starting line number to 4.
* `linenums`- value may be `true`, `false`, or a `number`. When not specified, line numbers default to `false` (i.e. no line numbers are displayed). The rarely used `number` option starts line numbering at the given value. `linenums=4` sets the starting line number to 4.
* `class`- code snippets can be styled with the CSS classes `no-box`, `code-shell`, and `avoid`.
@ -465,8 +465,6 @@ A couple of observations:
1. Omitting the `header` is fine when the source of the fragment is obvious. We just said that this is a fragment of the `app.module.ts` file which was displayed immediately above, in full, with a header.
There's no need to repeat the header.
1. The line numbers disappeared. By default, the doc viewer omits line numbers when there are fewer than 10 lines of code; it adds line numbers after that. You can turn line numbers on or off explicitly by setting the `linenums` attribute.
#### Example of bad code
Sometimes you want to display an example of bad code or bad design.
@ -496,18 +494,18 @@ Code tabs display code much like _code examples_ do. The added advantage is tha
#### Code-tabs attributes
* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are enabled only when code for a tab pane has greater than 10 lines of code.
* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, it defaults to `false`.
#### Code-pane attributes
* `path` - a file in the content/examples folder
* `header` - seen in the header of a tab
* `linenums` - overrides the `linenums` property at the `code-tabs` level for this particular pane. The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are enabled only when the number of lines of code are greater than 10.
* `linenums` - overrides the `linenums` property at the `code-tabs` level for this particular pane. The value can be `true`, `false` or a number indicating the starting line number. If not specified, it defaults to `false`.
The next example displays multiple code tabs, each with its own header.
It demonstrates control over display of line numbers at both the `<code-tabs>` and `<code-pane>` levels.
<code-tabs linenums="false">
<code-tabs linenums="true">
<code-pane
header="app.component.html"
path="docs-style-guide/src/app/app.component.html">
@ -515,7 +513,7 @@ It demonstrates control over display of line numbers at both the `<code-tabs>` a
<code-pane
header="app.component.ts"
path="docs-style-guide/src/app/app.component.ts"
linenums="true">
linenums="false">
</code-pane>
<code-pane
header="app.component.css (heroes)"
@ -530,11 +528,11 @@ It demonstrates control over display of line numbers at both the `<code-tabs>` a
Here's the markup for that example.
Note how the `linenums` attribute in the `<code-tabs>` explicitly disables numbering for all panes.
The `linenums` attribute in the second pane restores line numbering for _itself only_.
Note how the `linenums` attribute in the `<code-tabs>` explicitly enables numbering for all panes.
The `linenums` attribute in the second pane disables line numbering for _itself only_.
```html
<code-tabs linenums="false">
<code-tabs linenums="true">
<code-pane
header="app.component.html"
path="docs-style-guide/src/app/app.component.html">
@ -542,7 +540,7 @@ The `linenums` attribute in the second pane restores line numbering for _itself
<code-pane
header="app.component.ts"
path="docs-style-guide/src/app/app.component.ts"
linenums="true">
linenums="false">
</code-pane>
<code-pane
header="app.component.css (heroes)"

10
aio/content/marketing/test.html
View File

@ -3,7 +3,7 @@
<h2>&lt;code-tabs&gt;</h2>
<p>No linenums at code-tabs level</p>
<code-tabs >
<code-tabs>
<code-pane header='TS code file' language='ts'>
class {
foo(param: string) {}
@ -26,7 +26,7 @@
</code-tabs>
<p></p>
<p>No linenums at code-tabs level; linenums=true for HTML pane</p>
<p>No linenums at code-tabs level; linenums=true for second HTML pane</p>
<code-tabs >
<code-pane header='TS code file' language='ts'>
class {
@ -43,8 +43,8 @@
<p>One line.</p>
<code-example>const foo = 'bar'</code-example>
<p>Multi-line, linenums=false.</p>
<code-example linenums='false'>
<p>Multi-line, linenums=true.</p>
<code-example linenums='true'>
&lt;hero-details <em>nghost-pmm-5&gt;
&lt;h2 </em>ngcontent-pmm-5&gt;Bah Dah Bing&lt;/h2&gt;
&lt;hero-team <em>ngcontent-pmm-5 </em>nghost-pmm-6&gt;
@ -53,7 +53,7 @@
&lt;/hero-details&gt;
</code-example>
<p>Default linenums.</p>
<p>Default linenums (false).</p>
<code-example>
&lt;hero-details <em>nghost-pmm-5&gt;
&lt;h2 </em>ngcontent-pmm-5&gt;Mister Fantastic&lt;/h2&gt;

46
aio/src/app/custom-elements/code/code.component.spec.ts
View File

@ -71,34 +71,52 @@ describe('CodeComponent', () => {
`Formatted code (language: auto, linenums: true): ${oneLineCode}`);
});
it('should format a small multi-line code without linenums by default', async () => {
it('should format a small multi-line code sample without linenums by default', () => {
hostComponent.setCode(smallMultiLineCode);
expect(getFormattedCode()).toBe(
`Formatted code (language: auto, linenums: false): ${smallMultiLineCode}`);
});
it('should add line numbers to a big multi-line code by default', async () => {
it('should add line numbers to a small multi-line code sample when linenums is `true`', () => {
hostComponent.setCode(smallMultiLineCode);
hostComponent.linenums = true;
fixture.detectChanges();
expect(getFormattedCode()).toBe(
`Formatted code (language: auto, linenums: true): ${smallMultiLineCode}`);
});
it('should add line numbers to a small multi-line code sample when linenums is `\'true\'`', () => {
hostComponent.setCode(smallMultiLineCode);
hostComponent.linenums = 'true';
fixture.detectChanges();
expect(getFormattedCode()).toBe(
`Formatted code (language: auto, linenums: true): ${smallMultiLineCode}`);
});
it('should format a big multi-line code without linenums by default', () => {
hostComponent.setCode(bigMultiLineCode);
expect(getFormattedCode()).toBe(
`Formatted code (language: auto, linenums: false): ${bigMultiLineCode}`);
});
it('should add line numbers to a big multi-line code sample when linenums is `true`', () => {
hostComponent.setCode(bigMultiLineCode);
hostComponent.linenums = true;
fixture.detectChanges();
expect(getFormattedCode()).toBe(
`Formatted code (language: auto, linenums: true): ${bigMultiLineCode}`);
});
it('should format big multi-line code without linenums when linenums is `false`', async () => {
it('should add line numbers to a big multi-line code sample when linenums is `\'true\'`', () => {
hostComponent.setCode(bigMultiLineCode);
hostComponent.linenums = false;
hostComponent.linenums = 'true';
fixture.detectChanges();
expect(getFormattedCode()).toBe(
`Formatted code (language: auto, linenums: false): ${bigMultiLineCode}`);
});
it('should format big multi-line code without linenums when linenums is `\'false\'`', async () => {
hostComponent.setCode(bigMultiLineCode);
hostComponent.linenums = 'false';
fixture.detectChanges();
expect(getFormattedCode()).toBe(
`Formatted code (language: auto, linenums: false): ${bigMultiLineCode}`);
`Formatted code (language: auto, linenums: true): ${bigMultiLineCode}`);
});
});

10
aio/src/app/custom-elements/code/code.component.ts
View File

@ -5,12 +5,6 @@ import { CopierService } from 'app/shared/copier.service';
import { MatSnackBar } from '@angular/material/snack-bar';
import { tap } from 'rxjs/operators';
/**
* If linenums is not set, this is the default maximum number of lines that
* an example can display without line numbers.
*/
const DEFAULT_LINE_NUMS_COUNT = 10;
/**
* Formatted Code Block
*
@ -170,9 +164,7 @@ export class CodeComponent implements OnChanges {
typeof this.linenums === 'string' ? parseInt(this.linenums, 10) :
this.linenums;
// if no linenums, enable line numbers if more than one line
return linenums == null || isNaN(linenums as number) ?
(code.match(/\n/g) || []).length > DEFAULT_LINE_NUMS_COUNT : linenums;
return (linenums != null) && !isNaN(linenums as number) && linenums;
}
}