docs(aio): remove unnecessary anchor links from styleguide

This commit is contained in:
Peter Bacon Darwin 2017-05-01 19:03:27 +01:00 committed by Pete Bacon Darwin
parent ea9d8a6bc7
commit 5ba8c14893
1 changed files with 263 additions and 199 deletions

View File

@ -106,9 +106,11 @@ Apply the
to all components, services, and other symbols. to all components, services, and other symbols.
This helps make the app cleaner, easier to read and maintain, and more testable. This helps make the app cleaner, easier to read and maintain, and more testable.
### {@a 01-01}Rule of One {@a 01-01}
#### <a href="#01-01">Style 01-01</a> ### Rule of One
#### Style 01-01
<div class="s-rule do"> <div class="s-rule do">
@ -221,9 +223,11 @@ As the app grows, this rule becomes even more important.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 01-02}Small functions {@a 01-02}
#### <a href="#01-02">Style 01-02</a> ### Small functions
#### Style 01-02
<div class="s-rule do"> <div class="s-rule do">
@ -310,9 +314,11 @@ Naming conventions are hugely important to maintainability and readability. This
### {@a 02-01}General Naming Guidelines {@a 02-01}
#### <a href="#02-01">Style 02-01</a> ### General Naming Guidelines
#### Style 02-01
<div class="s-rule do"> <div class="s-rule do">
@ -371,9 +377,11 @@ Naming conventions are hugely important to maintainability and readability. This
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 02-02}Separate file names with dots and dashes {@a 02-02}
#### <a href="#02-02">Style 02-02</a> ### Separate file names with dots and dashes
#### Style 02-02
<div class="s-rule do"> <div class="s-rule do">
@ -467,9 +475,11 @@ Abbreviations such as `.srv`, `.svc`, and `.serv` can be confusing.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 02-03}Symbols and file names {@a 02-03}
#### <a href="#02-03">Style 02-03</a> ### Symbols and file names
#### Style 02-03
<div class="s-rule do"> <div class="s-rule do">
@ -721,10 +731,11 @@ and reference assets of different types.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 02-04}Service names {@a 02-04}
#### <a href="#02-04">Style 02-04</a> ### Service names
#### Style 02-04
<div class="s-rule do"> <div class="s-rule do">
@ -875,9 +886,11 @@ As always, strive for consistency.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 02-05}Bootstrapping {@a 02-05}
#### <a href="#02-05">Style 02-05</a> ### Bootstrapping
#### Style 02-05
<div class="s-rule do"> <div class="s-rule do">
@ -943,10 +956,11 @@ As always, strive for consistency.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 02-06}
### {@a 02-06}Directive selectors ### Directive selectors
#### <a href="#02-06">Style 02-06</a> #### Style 02-06
<div class="s-rule do"> <div class="s-rule do">
@ -982,10 +996,11 @@ As always, strive for consistency.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 02-07}
### {@a 02-07}Custom prefix for components ### Custom prefix for components
#### <a href="#02-07">Style 02-07</a> #### Style 02-07
<div class="s-rule do"> <div class="s-rule do">
@ -1088,10 +1103,11 @@ For example, the prefix `toh` represents from **T**our **o**f **H**eroes and the
### {@a 02-08}Custom prefix for directives {@a 02-08}
#### <a href="#02-08">Style 02-08</a> ### Custom prefix for directives
#### Style 02-08
<div class="s-rule do"> <div class="s-rule do">
@ -1154,10 +1170,11 @@ For example, the prefix `toh` represents from **T**our **o**f **H**eroes and the
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 02-09}Pipe names {@a 02-09}
#### <a href="#02-09">Style 02-09</a> ### Pipe names
#### Style 02-09
<div class="s-rule do"> <div class="s-rule do">
@ -1248,10 +1265,11 @@ For example, the prefix `toh` represents from **T**our **o**f **H**eroes and the
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 02-10}Unit test file names {@a 02-10}
#### <a href="#02-10">Style 02-10</a> ### Unit test file names
#### Style 02-10
<div class="s-rule do"> <div class="s-rule do">
@ -1386,10 +1404,11 @@ For example, the prefix `toh` represents from **T**our **o**f **H**eroes and the
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 02-11}_End-to-End_ (E2E) test file names {@a 02-11}
#### <a href="#02-11">Style 02-11</a> ### _End-to-End_ (E2E) test file names
#### Style 02-11
<div class="s-rule do"> <div class="s-rule do">
@ -1474,10 +1493,11 @@ For example, the prefix `toh` represents from **T**our **o**f **H**eroes and the
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 02-12}
### {@a 02-12}Angular _NgModule_ names ### Angular _NgModule_ names
#### <a href="#02-12">Style 02-12</a> #### Style 02-12
<div class="s-rule do"> <div class="s-rule do">
@ -1709,10 +1729,11 @@ Have a consistent set of coding, naming, and whitespace conventions.
### {@a 03-01}Classes {@a 03-01}
#### <a href="#03-01">Style 03-01</a> ### Classes
#### Style 03-01
<div class="s-rule do"> <div class="s-rule do">
@ -1765,10 +1786,11 @@ By convention, upper camel case indicates a constructable asset.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 03-02}Constants {@a 03-02}
#### <a href="#03-02">Style 03-02</a> ### Constants
#### Style 03-02
<div class="s-rule do"> <div class="s-rule do">
@ -1873,10 +1895,11 @@ It is rarely worth the effort to change them at the risk of breaking existing co
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 03-03}Interfaces {@a 03-03}
#### <a href="#03-03">Style 03-03</a> ### Interfaces
#### Style 03-03
<div class="s-rule do"> <div class="s-rule do">
@ -1972,10 +1995,11 @@ discourage the `I` prefix.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 03-04}
### {@a 03-04}Properties and methods ### Properties and methods
#### <a href="#03-04">Style 03-04</a> #### Style 03-04
<div class="s-rule do"> <div class="s-rule do">
@ -2049,10 +2073,11 @@ discourage the `I` prefix.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 03-06}
### {@a 03-06}Import line spacing ### Import line spacing
#### <a href="#03-06">Style 03-06</a> #### Style 03-06
<div class="s-rule consider"> <div class="s-rule consider">
@ -2140,10 +2165,11 @@ You didn't write them and you don't want them cluttering `src`.
Use the naming conventions for files in this guide. Use the naming conventions for files in this guide.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-01}
### {@a 04-01}_LIFT_ ### _LIFT_
#### <a href="#04-01">Style 04-01</a> #### Style 04-01
<div class="s-rule do"> <div class="s-rule do">
@ -2184,10 +2210,11 @@ _can I quickly open and start work in all of the related files for this feature_
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-02}
### {@a 04-02}Locate ### Locate
#### <a href="#04-02">Style 04-02</a> #### Style 04-02
<div class="s-rule do"> <div class="s-rule do">
@ -2215,10 +2242,11 @@ A descriptive folder structure makes a world of difference to you and the people
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-03}
### {@a 04-03}Identify ### Identify
#### <a href="#04-03">Style 04-03</a> #### Style 04-03
<div class="s-rule do"> <div class="s-rule do">
@ -2280,10 +2308,11 @@ in a single file than as multiple files. Be wary of this loophole.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 04-04}Flat {@a 04-04}
#### <a href="#04-04">Style 04-04</a> ### Flat
#### Style 04-04
<div class="s-rule do"> <div class="s-rule do">
@ -2339,10 +2368,11 @@ Use a flatter structure until there is an obvious value to creating a new folder
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 04-05}_T-DRY_ (Try to be _DRY_) {@a 04-05}
#### <a href="#04-05">Style 04-05</a> ### _T-DRY_ (Try to be _DRY_)
#### Style 04-05
<div class="s-rule do"> <div class="s-rule do">
@ -2382,10 +2412,11 @@ But if something is not obvious or departs from a convention, then spell it out.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 04-06}Overall structural guidelines {@a 04-06}
#### <a href="#04-06">Style 04-06</a> ### Overall structural guidelines
#### Style 04-06
<div class="s-rule do"> <div class="s-rule do">
@ -2701,10 +2732,11 @@ Whatever you choose, be consistent.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-07}
### {@a 04-07}_Folders-by-feature_ structure ### _Folders-by-feature_ structure
#### <a href="#04-07">Style 04-07</a> #### Style 04-07
<div class="s-rule do"> <div class="s-rule do">
@ -2808,10 +2840,11 @@ and more difficult in a flat structure.
</a> </a>
### {@a 04-08}App _root module_ {@a 04-08}
#### <a href="#04-08">Style 04-08</a> ### App _root module_
#### Style 04-08
<div class="s-rule do"> <div class="s-rule do">
@ -2867,9 +2900,11 @@ for example, in `/src/app`.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 04-09}Feature modules {@a 04-09}
#### <a href="#04-09">Style 04-09</a> ### Feature modules
#### Style 04-09
<div class="s-rule do"> <div class="s-rule do">
@ -2986,10 +3021,11 @@ area, folder, and file; for example, `app/heroes/heroes.module.ts` defines `Hero
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-10}
### {@a 04-10}Shared feature module ### Shared feature module
#### <a href="#04-10">Style 04-10</a> #### Style 04-10
<div class="s-rule do"> <div class="s-rule do">
@ -3237,10 +3273,11 @@ Yet there is a real danger of that happening if the `SharedModule` provides a se
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-11}
### {@a 04-11}Core feature module ### Core feature module
#### <a href="#04-11">Style 04-11</a> #### Style 04-11
<div class="s-rule consider"> <div class="s-rule consider">
@ -3563,10 +3600,11 @@ Yet there is a real danger of that happening accidentally if the `CoreModule` pr
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-12}
### {@a 04-12}Prevent re-import of the core module ### Prevent re-import of the core module
#### <a href="#04-12">Style 04-12</a> #### Style 04-12
Only the root `AppModule` should import the `CoreModule`. Only the root `AppModule` should import the `CoreModule`.
@ -3620,10 +3658,11 @@ Only the root `AppModule` should import the `CoreModule`.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-13}
### {@a 04-13}Lazy Loaded folders ### Lazy Loaded folders
#### <a href="#04-13">Style 04-13</a> #### Style 04-13
A distinct application feature or workflow may be *lazy loaded* or *loaded on demand* rather than when the application starts. A distinct application feature or workflow may be *lazy loaded* or *loaded on demand* rather than when the application starts.
@ -3651,10 +3690,11 @@ A typical *lazy loaded folder* contains a *routing component*, its child compone
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 04-14}
### {@a 04-14}Never directly import lazy loaded folders ### Never directly import lazy loaded folders
#### <a href="#04-14">Style 04-14</a> #### Style 04-14
<div class="s-rule avoid"> <div class="s-rule avoid">
@ -3682,9 +3722,11 @@ A typical *lazy loaded folder* contains a *routing component*, its child compone
## Components ## Components
### {@a 05-02}Component selector names {@a 05-02}
#### <a href="#05-02">Style 05-02</a> ### Component selector names
#### Style 05-02
<div class="s-rule do"> <div class="s-rule do">
@ -3733,10 +3775,11 @@ A typical *lazy loaded folder* contains a *routing component*, its child compone
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 05-03}
### {@a 05-03}Components as elements ### Components as elements
#### <a href="#05-03">Style 05-03</a> #### Style 05-03
<div class="s-rule do"> <div class="s-rule do">
@ -3806,10 +3849,11 @@ Developers place components on the page as they would native HTML elements and w
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 05-04}
### {@a 05-04}Extract templates and styles to their own files ### Extract templates and styles to their own files
#### <a href="#05-04">Style 05-04</a> #### Style 05-04
<div class="s-rule do"> <div class="s-rule do">
@ -3931,10 +3975,11 @@ in those editors that support it; it won't help with CSS styles.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 05-12}
### {@a 05-12}Decorate _input_ and _output_ properties ### Decorate _input_ and _output_ properties
#### <a href="#05-12">Style 05-12</a> #### Style 05-12
<div class="s-rule do"> <div class="s-rule do">
@ -4023,9 +4068,11 @@ Put it on the line above when doing so is clearly more readable.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
### {@a 05-13}Avoid aliasing _inputs_ and _outputs_ {@a 05-13}
#### <a href="#05-13">Style 05-13</a> ### Avoid aliasing _inputs_ and _outputs_
#### Style 05-13
<div class="s-rule avoid"> <div class="s-rule avoid">
@ -4098,10 +4145,11 @@ and the directive name doesn't describe the property.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 05-14}
### {@a 05-14}Member sequence ### Member sequence
#### <a href="#05-14">Style 05-14</a> #### Style 05-14
<div class="s-rule do"> <div class="s-rule do">
@ -4154,10 +4202,11 @@ helps instantly identify which members of the component serve which purpose.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 05-15}
### {@a 05-15}Delegate complex component logic to services ### Delegate complex component logic to services
#### <a href="#05-15">Style 05-15</a> #### Style 05-15
<div class="s-rule do"> <div class="s-rule do">
@ -4242,10 +4291,11 @@ helps instantly identify which members of the component serve which purpose.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 05-16}
### {@a 05-16}Don't prefix _output_ properties ### Don't prefix _output_ properties
#### <a href="#05-16">Style 05-16</a> #### Style 05-16
<div class="s-rule do"> <div class="s-rule do">
@ -4324,10 +4374,11 @@ helps instantly identify which members of the component serve which purpose.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 05-17}
### {@a 05-17}Put presentation logic in the component class ### Put presentation logic in the component class
#### <a href="#05-17">Style 05-17</a> #### Style 05-17
<div class="s-rule do"> <div class="s-rule do">
@ -4382,11 +4433,11 @@ helps instantly identify which members of the component serve which purpose.
## Directives ## Directives
{@a 06-01}
### Use directives to enhance an element
### {@a 06-01}Use directives to enhance an element #### Style 06-01
#### <a href="#06-01">Style 06-01</a>
<div class="s-rule do"> <div class="s-rule do">
@ -4438,10 +4489,11 @@ helps instantly identify which members of the component serve which purpose.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 06-03}
### {@a 06-03}_HostListener_/_HostBinding_ decorators versus _host_ metadata ### _HostListener_/_HostBinding_ decorators versus _host_ metadata
#### <a href="#06-03">Style 06-03</a> #### Style 06-03
<div class="s-rule consider"> <div class="s-rule consider">
@ -4512,9 +4564,11 @@ Compare with the less preferred `host` metadata alternative.
## Services ## Services
### {@a 07-01}Services are singletons {@a 07-01}
#### <a href="#07-01">Style 07-01</a> ### Services are singletons
#### Style 07-01
<div class="s-rule do"> <div class="s-rule do">
@ -4558,10 +4612,11 @@ Compare with the less preferred `host` metadata alternative.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 07-02}
### {@a 07-02}Single responsibility ### Single responsibility
#### <a href="#07-02">Style 07-02</a> #### Style 07-02
<div class="s-rule do"> <div class="s-rule do">
@ -4608,10 +4663,11 @@ Compare with the less preferred `host` metadata alternative.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 07-03}
### {@a 07-03}Providing a service ### Providing a service
#### <a href="#07-03">Style 07-03</a> #### Style 07-03
<div class="s-rule do"> <div class="s-rule do">
@ -4686,10 +4742,11 @@ that instance is shared and available to all child components of that top level
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 07-04}
### {@a 07-04}Use the @Injectable() class decorator ### Use the @Injectable() class decorator
#### <a href="#07-04">Style 07-04</a> #### Style 07-04
<div class="s-rule do"> <div class="s-rule do">
@ -4745,9 +4802,11 @@ dependencies based on the declared types of that service's constructor parameter
## Data Services ## Data Services
### {@a 08-01}Talk to the server through a service {@a 08-01}
#### <a href="#08-01">Style 08-01</a> ### Talk to the server through a service
#### Style 08-01
<div class="s-rule do"> <div class="s-rule do">
@ -4815,12 +4874,14 @@ easier to test the consumers with mock service implementations.
## Lifecycle hooks ## Lifecycle hooks
Use Lifecycle hooks to tap into important events exposed by Angular. Use Lifecycle hooks to tap into important events exposed by Angular.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a 09-01}
### {@a 09-01}Implement lifecycle hook interfaces ### Implement lifecycle hook interfaces
#### <a href="#09-01">Style 09-01</a> #### Style 09-01
<div class="s-rule do"> <div class="s-rule do">
@ -4866,12 +4927,14 @@ signatures. use those signatures to flag spelling and syntax mistakes.
## Appendix ## Appendix
Useful tools and tips for Angular. Useful tools and tips for Angular.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a A-01}
### {@a A-01}Codelyzer ### Codelyzer
#### <a href="#A-01">Style A-01</a> #### Style A-01
<div class="s-rule do"> <div class="s-rule do">
@ -4896,10 +4959,11 @@ Useful tools and tips for Angular.
<a href="#toc">Back to top</a> <a href="#toc">Back to top</a>
{@a A-02}
### {@a A-02}File templates and snippets ### File templates and snippets
#### <a href="#A-02">Style A-02</a> #### Style A-02
<div class="s-rule do"> <div class="s-rule do">