docs: add NgModule docs #20306

kapunahelewong · 2017-11-09T18:55:40Z

PR Checklist

Please check if your PR fulfills the following requirements:

The commit message follows our guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[x] Documentation content changes
[ ] angular.io application / infrastructure changes
[ ] Other... Please describe:

What is the current behavior?

NgModules info is in two docs.
Issue Number: N/A

What is the new behavior?

NgModules is broken up by topic.

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

Closes #21257 #18957 #18799 #17825

mhevery · 2017-11-22T04:41:42Z

aio/content/guide/bootstrapping.md


-* **[_providers_](#providers)** &mdash; there are none to start but you are likely to add some soon.
+You must declare every component in an `NgModule` class. 


...every component in exactly one NgModule...

mhevery · 2017-11-22T04:44:06Z

aio/content/guide/bootstrapping.md

-* **[_providers_](#providers)** &mdash; there are none to start but you are likely to add some soon.
+You must declare every component in an `NgModule` class. 
+If you use a component without declaring it, Angular returns an 
+error message in the browser console.


is on the browser console necessary? Where else would the error be? Less words is better.

mhevery · 2017-11-22T04:46:44Z

aio/content/guide/bootstrapping.md

+
+```
+
+The `import` statements at the top make the code in those files available to 


import is standard ES6 stuff, i don't think we need to talk about it. We just expect the reader to know. Less is better.

mhevery · 2017-11-22T04:49:37Z

aio/content/guide/bootstrapping.md


-The `@NgModule` properties for the minimal `AppModule` generated by the CLI are as follows:
+* **_declarations_**&mdash;this application's lone component.
+* **_imports_**&mdash;the `BrowserModule` that applications need to run in a browser.


not sure what you are trying to say here. I would say: Import BrowserModule to have browser specific services such as DOM rendering, sanitization, and location.

mhevery · 2017-11-22T04:50:43Z

aio/content/guide/bootstrapping.md


+Whereas the `imports` array is for importing NgModules, 


Why are we talking about imports all of a sudden? Also the grammar of the sentence is weird. I would omit the import as it it not relevant to declarations.

mhevery · 2017-11-22T04:54:11Z

aio/content/guide/bootstrapping.md


-### The _declarations_ array
+**Only `@NgModule` classes** go in the `imports` array. Do not put any other kind of class in `imports`.


I would say only NgModule references go in .... (The fact that they are classes is incidental). Also is the second sentence necessary? it says the same as first. Less is better.

mhevery · 2017-11-22T04:56:07Z

aio/content/guide/bootstrapping.md

-You'll learn to create two other kinds of classes &mdash;
-[directives](guide/attribute-directives) and [pipes](guide/pipes) &mdash;
-that you must also add to the `declarations` array.
+A common use of the `declarations` array is using directives.


more active voice: Use declarations for ....

Thank you. Done.

mhevery · 2017-11-22T04:57:45Z

aio/content/guide/bootstrapping.md

-[directives](guide/attribute-directives) and [pipes](guide/pipes) &mdash;
-that you must also add to the `declarations` array.
+A common use of the `declarations` array is using directives.
+For example, when you create a directive and use it in a template, such as in the [Attribute Directives](guide/attribute-directives) page, you need to add it to the relevant NgModule `declarations` array. Relevant here means the NgModule that the directive or component belongs to. In simple apps with only the root module, everything belongs to that one module. However, for apps with more than one module, certain directives, components, and pipes belong to one module or another. To use a directive, component, or pipe in a module, you must do a few things:


this sounds like a repeat what you already told me above. Also why "Attribute Directives"? Why not directives in general?

You're right. Fixed.

mhevery · 2017-11-22T04:59:53Z

aio/content/guide/bootstrapping.md


-</div>
+Those three steps look like the following. In the file where you create your directive, export it. 


I feel like there is way to much text/detail about how to do this. Assume reader knows how to import/export things in ES6, it should be prerequisite.

@jenniferfell I agree with this point (and am adding pre-requisites at the top), but as this kind of guidance is throughout the docs and this is intro level doc, I'd like to get your thoughts on how we can apply this systematically yet make sure there's a clear point of reference for those who don't know.

mhevery · 2017-11-22T05:01:23Z

aio/content/guide/bootstrapping.md

-Before DI can inject a service, it must create that service with the help of a _provider_.
-You can tell DI about a service's _provider_ in a number of ways.
-Among the most popular ways is to register the service in the root `ngModule.providers` array, which will make that service available _everywhere_. 
+The module's `imports` array appears exclusively in the `@NgModule` metadata object.


don't refer to other @NgModule as classes but references.

Got it. Thanks!

mary-poppins · 2017-12-09T19:21:19Z

You can preview 01d5931 at https://pr20306-01d5931.ngbuilds.io/.

mary-poppins · 2017-12-09T21:38:47Z

You can preview 43af2a4 at https://pr20306-43af2a4.ngbuilds.io/.

mary-poppins · 2017-12-10T02:50:52Z

You can preview f045256 at https://pr20306-f045256.ngbuilds.io/.

mary-poppins · 2017-12-10T14:20:05Z

You can preview dc7b19c at https://pr20306-dc7b19c.ngbuilds.io/.

mary-poppins · 2018-01-09T19:49:50Z

You can preview 788bcb5 at https://pr20306-788bcb5.ngbuilds.io/.

alexeagle · 2018-01-09T22:14:42Z

@kara 💚 no google3 change

gkalpak

From a quick look, there seem to be some changes that should not be included and Travis is red. I know the current failures are unrelated to this PR, but they must have been fixed on master and might have been covering real failures.

I will take more thorough look tomorrow (pre- or post-merge 😃).

BTW, not directly related to this PR, but the unit test files for examples are not actually used in any tests (afaict). This means they can become outdated ot even break without us noticing, which might be frustrating for people trying to use them (e.g. by downloading the zips) 😞

gkalpak · 2018-01-09T22:24:52Z

aio/tools/transforms/angular.io-package/index.js


-    checkAnchorLinksProcessor.$enabled = true;
+    checkAnchorLinksProcessor.$enabled = false;


I assume these are not supposed to be part of the PR, right?

Oh man, yeah! I forgot I'd changed this while I wrote so I could see it rendered. Thanks for catching this.

gkalpak · 2018-01-09T22:31:41Z

aio/yarn.lock

+  resolved "https://registry.yarnpkg.com/debug/-/debug-2.6.8.tgz#e731531ca2ede27d188222427da17821d68ff4fc"
+  dependencies:
+    ms "2.0.0"
+


I don't think this change should be included in the PR either.

Thank you for catching this. I've fixed it. :)

gkalpak · 2018-01-10T13:01:34Z

The Travis failures are "legit" 😃

mary-poppins · 2018-01-10T18:48:33Z

You can preview a8ee8f7 at https://pr20306-a8ee8f7.ngbuilds.io/.

mary-poppins · 2018-01-10T18:54:47Z

You can preview 9871e8e at https://pr20306-9871e8e.ngbuilds.io/.

alexeagle · 2018-01-10T20:10:01Z

Looks not ready to merge, due to Travis failure:


ERROR in Error: Could not resolve module ./app/customers/customers.module relative to /home/travis/build/angular/angular/aio/content/examples/lazy-loading/src/app/app-routing.module.ts
    at StaticSymbolResolver.getSymbolByModule (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@angular/compiler/bundles/compiler.umd.js:29757:30)
    at StaticReflector.resolveExternalReference (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@angular/compiler/bundles/compiler.umd.js:31594:62)
    at parseLazyRoute (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@angular/compiler/bundles/compiler.umd.js:29043:55)
    at listLazyRoutes (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@angular/compiler/bundles/compiler.umd.js:29005:36)
    at visitLazyRoute (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@angular/compiler/bundles/compiler.umd.js:31167:47)
    at AotCompiler.listLazyRoutes (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@angular/compiler/bundles/compiler.umd.js:31135:20)
    at AngularCompilerProgram.listLazyRoutes (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@angular/compiler-cli/src/transformers/program.js:156:30)
    at Function.NgTools_InternalApi_NG_2.listLazyRoutes (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@angular/compiler-cli/src/ngtools_api.js:44:36)
    at AngularCompilerPlugin._getLazyRoutesFromNgtools (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@ngtools/webpack/src/angular_compiler_plugin.js:246:66)
    at Promise.resolve.then.then (/home/travis/build/angular/angular/aio/tools/examples/shared/node_modules/@ngtools/webpack/src/angular_compiler_plugin.js:542:50)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:188:7)
webpack: Failed to compile.
Build did not succeed. Please fix errors before running e2e task

mary-poppins · 2018-01-10T22:15:26Z

You can preview 852e63f at https://pr20306-852e63f.ngbuilds.io/.

kapunahelewong · 2018-01-10T22:39:07Z

Hi @alexeagle I got it green!!! :D

Thank you for your help. :)

PR Close #20306

PR Close angular#20306

angular-automatic-lock-bot · 2019-09-13T04:21:00Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

googlebot added the cla: yes label Nov 9, 2017

kapunahelewong changed the title ~~docs(aio): add NgModule docs~~ [WIP]docs(aio): add NgModule docs Nov 9, 2017

kapunahelewong force-pushed the wong-ngmodules branch from 9d0fee1 to 795e89a Compare November 10, 2017 16:43

jasonaden added the comp: docs label Nov 14, 2017

gkalpak closed this Nov 17, 2017

gkalpak reopened this Nov 17, 2017

kapunahelewong force-pushed the wong-ngmodules branch from 795e89a to 5d72130 Compare November 20, 2017 21:32

mhevery reviewed Nov 22, 2017

View reviewed changes

kapunahelewong closed this Nov 27, 2017

kapunahelewong reopened this Nov 27, 2017

kapunahelewong force-pushed the wong-ngmodules branch from 1dc5f75 to 6a8e69f Compare November 27, 2017 23:33

gkalpak closed this Nov 28, 2017

gkalpak reopened this Nov 28, 2017

jenniferfell added this to the 5.1.2-sprint milestone Dec 8, 2017

jenniferfell self-requested a review December 8, 2017 22:14

manughub assigned kapunahelewong Dec 8, 2017

kapunahelewong force-pushed the wong-ngmodules branch 4 times, most recently from cec5d62 to 01d5931 Compare December 9, 2017 19:13

kapunahelewong force-pushed the wong-ngmodules branch from f045256 to dc7b19c Compare December 10, 2017 14:10

gkalpak mentioned this pull request Dec 11, 2017

ngmodules examples for final is not building #20928

Closed

kapunahelewong force-pushed the wong-ngmodules branch from dc7b19c to 6e8bdfc Compare December 15, 2017 22:16

kapunahelewong changed the title ~~[WIP]docs(aio): add NgModule docs~~ docs(aio): add NgModule docs Dec 19, 2017

kapunahelewong mentioned this pull request Dec 21, 2017

docs: clarify the use of classes and interfaces in style guide #20919

Closed

1 task

kapunahelewong mentioned this pull request Jan 3, 2018

EntryComponents Not Documented #21257

Closed

kapunahelewong force-pushed the wong-ngmodules branch from 9a26c18 to 788bcb5 Compare January 9, 2018 19:33

gkalpak reviewed Jan 9, 2018

View reviewed changes

kapunahelewong force-pushed the wong-ngmodules branch from 788bcb5 to e25fc1d Compare January 10, 2018 12:02

docs(aio): add NgModule docs

a8ee8f7

kapunahelewong force-pushed the wong-ngmodules branch from e25fc1d to a8ee8f7 Compare January 10, 2018 18:41

docs: fix yarn.lock

9871e8e

alexeagle removed the action: merge The PR is ready for merge by the caretaker label Jan 10, 2018

docs: fix lazy-loading example

852e63f

kapunahelewong changed the title ~~docs(aio): add NgModule docs~~ docs: add NgModule docs Jan 10, 2018

alexeagle added the action: merge The PR is ready for merge by the caretaker label Jan 11, 2018

alexeagle pushed a commit that referenced this pull request Jan 11, 2018

docs(aio): add NgModule docs (#20306)

64d4aaf

PR Close #20306

alexeagle pushed a commit that referenced this pull request Jan 11, 2018

docs: fix yarn.lock (#20306)

50b6056

PR Close #20306

alexeagle pushed a commit that referenced this pull request Jan 11, 2018

docs: fix lazy-loading example (#20306)

3db02d2

PR Close #20306

alexeagle closed this in 53f9118 Jan 11, 2018

alexeagle pushed a commit that referenced this pull request Jan 11, 2018

docs: fix yarn.lock (#20306)

f82013f

PR Close #20306

alexeagle pushed a commit that referenced this pull request Jan 11, 2018

docs: fix lazy-loading example (#20306)

456f57d

PR Close #20306

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

docs(aio): add NgModule docs (angular#20306)

c21084a

PR Close angular#20306

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

docs: fix yarn.lock (angular#20306)

2752749

PR Close angular#20306

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

docs: fix lazy-loading example (angular#20306)

ca23e06

PR Close angular#20306

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 13, 2019


		* [_providers_](#providers) — there are none to start but you are likely to add some soon.
		You must declare every component in an `NgModule` class.


		```

		The `import` statements at the top make the code in those files available to


		### The _declarations_ array
		Only `@NgModule` classes go in the `imports` array. Do not put any other kind of class in `imports`.


		</div>
		Those three steps look like the following. In the file where you create your directive, export it.


		checkAnchorLinksProcessor.$enabled = true;
		checkAnchorLinksProcessor.$enabled = false;

docs: add NgModule docs #20306

docs: add NgModule docs #20306

Conversation

kapunahelewong commented Nov 9, 2017 • edited

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

Other information

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mary-poppins commented Dec 9, 2017

mary-poppins commented Dec 9, 2017

mary-poppins commented Dec 10, 2017

mary-poppins commented Dec 10, 2017

mary-poppins commented Jan 9, 2018

alexeagle commented Jan 9, 2018

gkalpak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kapunahelewong Jan 10, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gkalpak commented Jan 10, 2018

mary-poppins commented Jan 10, 2018

mary-poppins commented Jan 10, 2018

alexeagle commented Jan 10, 2018

mary-poppins commented Jan 10, 2018

kapunahelewong commented Jan 10, 2018

angular-automatic-lock-bot bot commented Sep 13, 2019

kapunahelewong commented Nov 9, 2017 •

edited

kapunahelewong Jan 10, 2018 •

edited