docs(boot): Docs for @loopback/boot #631

virkt25 · 2018-02-21T06:56:48Z

Documentation explaining the @loopback/boot extension and the various aspects that make it up.

Need a review and suggestions on the following:
-- Should individual Booters be documented here? (Or link to docs in README for the package?)
-- Layout?
-- Grammar?

dhmlau

While this doc might have good information on what boot is and how it works, I might miss the points (as a user):

why do i need to care about how boot if artifacts are automatically loaded for me when using CLI
in what case i need to know more about booters

dhmlau · 2018-02-22T14:45:02Z

pages/en/lb4/Booting-an-Application.md

+* Process those artifacts automatically (this usually means binding them to the Application)
+
+`@loopback/boot` provides a Bootstrapper that uses Booters to automatically
+discover and bind artifacts, all packaged in an easy to use Mixin.


"easy to use" => "easy-to-use"?

dhmlau · 2018-02-22T14:46:12Z

pages/en/lb4/Booting-an-Application.md

+### What is an artifact?
+
+An artifact is any LoopBack construct usually defined in code as a Class. The word
+artifact describes Controllers, Repositories, Models, etc.


Suggestion to reword the 2nd sentence:
LoopBack constructs include Controllers, Repositories.....

dhmlau · 2018-02-22T14:47:59Z

pages/en/lb4/Booting-an-Application.md

+### app.booters()
+
+A convenience method manually bind `Booters`. You can pass any number of `Booter`
+classes to this method and they will all get bound to the Application using the


get bound => get bounded

Is be bound better?

dhmlau · 2018-02-22T14:49:02Z

pages/en/lb4/Booting-an-Application.md

+
+## BootComponent
+
+This component is added to a Application by `BootMixin` if used. The Component:


"a Application" => "an Application"?
"The Component" => "This Component"

dhmlau · 2018-02-22T14:49:30Z

pages/en/lb4/Booting-an-Application.md

+## Bootstrapper
+
+A Class that acts as the "manager" for Booters. The Boostrapper is designed to be
+bound to an Application as a `SINGLETON`. The Bootstrapper class provides a `boot()`


bound -> bounded

dhmlau · 2018-02-22T14:50:14Z

pages/en/lb4/Booting-an-Application.md

+method. This method is responsible for getting all bound `Booters` and running
+their `phases`. A `phase` is a method on a `Booter` class.
+
+Each call of the `boot()` method creates a new `Context` that sets the `app` context


suggestion:
"Each call of the boot() method" => "Each boot() method call"

dhmlau · 2018-02-22T14:50:30Z

pages/en/lb4/Booting-an-Application.md

+their `phases`. A `phase` is a method on a `Booter` class.
+
+Each call of the `boot()` method creates a new `Context` that sets the `app` context
+as it's parent. This is done so each `Context` for `boot` gets a new instance of


it's parent => its parent

dhmlau · 2018-02-22T15:04:15Z

pages/en/lb4/Booting-an-Application.md

+
+## Usage: @loopback/cli
+
+New projects generated using `@loopback/cli` or `lb4` are automatically enabled


I wonder if it's a good idea to let the readers know up front that for general use, artifacts are automatically loaded for you and you don't need to know too much details.

shimks

Nice docs. It's missing a sidebar entry and there are some minor nitpicks, but once that's been taken care of, LGTM.

shimks · 2018-02-22T15:47:25Z

pages/en/lb4/Booting-an-Application.md

+#### Using the BootMixin
+
+`Booter` and `Binding` types must be imported alongside `BootMixin` to allow TypeScript
+to infer types and avoid errors. \_If using `tslint` with the `no-unused-variable` rule,


shimks · 2018-02-22T15:54:06Z

pages/en/lb4/Concepts.md

+  servers and bindings. The Application class extends [Context](Context.html), and
+  provides the controls for starting and stopping itself and its associated
+  servers.
+* [**Booting an Application**](Booting-an-Application.html): A convention based


I think the section on boot should be somewhere at the bottom if the order matters. Most users of LoopBack won't really have to know about the fine details of booters other than that they do context bindings for you. I think it'd be more appropriate below Context here.

shimks · 2018-02-22T15:55:25Z

pages/en/lb4/Booting-an-Application.md

+
+* Discover artifacts automatically based on a convention (a specific folder
+  containing files with a given suffix)
+* Process those artifacts automatically (this usually means binding them to the Application)


I think we should use fit in the concept of context in here somewhere, just to make sure that users understand that boot takes care of automatic context bindings.

virkt25 · 2018-02-23T05:36:52Z

@dhmlau Good points! Thoughts on splitting this doc into 2 different pages?

One for "users" of the Application (all they need to know is CLI projects are enables, how to add to manual application and the config options avaiable to them)
Another for Extension Developers who would have more of an interest in understanding how @loopback/boot works and how they can leverage this knowledge to write their own Booter -- realistically I think an extension developer just needs to know how to write a Booter which doesn't require details about the inner workings

Does anyone need to know how Boot works under the hood?

dhmlau · 2018-02-23T14:17:01Z

+1 on splitting into 2 pages or at least 2 sections.
I wonder if the split is MVP. But the other argument is we might as well get it all fixed at one time, rather than going back again when we have time.

kjdelisle

Excellent overall, just has some minor spelling, grammar and phrasing problems to address and then it can land.

kjdelisle · 2018-02-23T19:28:47Z

pages/en/lb4/Booting-an-Application.md

+Since this is a convention based Bootstrapper, it is important to set a `projectRoot`,
+as all other artifact paths will be resolved relative to this path.
+
+_Tip_: `application.ts` will likely be at the root of your project, so it's path can be


it's -> its

kjdelisle · 2018-02-23T19:28:54Z

pages/en/lb4/Booting-an-Application.md

+Components to set the property `booters` as an Array of `Booters`. They will be bound
+to the Application and called by the `Bootstrapper`.
+
+Since this is a convention based Bootstrapper, it is important to set a `projectRoot`,


convention-based

kjdelisle · 2018-02-23T19:29:23Z

pages/en/lb4/Booting-an-Application.md

+### app.boot()
+
+A convenience method to retrieve the `Bootstrapper` instance bound to the
+Application and calls it's `boot` function. This should be called before an


it's -> its

kjdelisle · 2018-02-23T19:29:49Z

pages/en/lb4/Booting-an-Application.md

+
+### app.booters()
+
+A convenience method manually bind `Booters`. You can pass any number of `Booter`


A convenience method to manually bind...

kjdelisle · 2018-02-23T19:30:00Z

pages/en/lb4/Booting-an-Application.md

+### app.booters()
+
+A convenience method manually bind `Booters`. You can pass any number of `Booter`
+classes to this method and they will all get bounded to the Application using the


..and they will all be bound...

kjdelisle · 2018-02-23T19:30:53Z

pages/en/lb4/Booting-an-Application.md

+
+## Bootstrapper
+
+A Class that acts as the "manager" for Booters. The Boostrapper is designed to be


Boostrapper -> Bootstrapper

:P

kjdelisle · 2018-02-23T19:31:14Z

pages/en/lb4/Booting-an-Application.md

+## Bootstrapper
+
+A Class that acts as the "manager" for Booters. The Boostrapper is designed to be
+bounded to an Application as a `SINGLETON`. The Bootstrapper class provides a `boot()`


bounded -> bound

kjdelisle · 2018-02-23T19:32:19Z

pages/en/lb4/Booting-an-Application.md

+`booters` but the same context can be passed into `boot` so selective `phases` can be
+run in different calls of `boot`.
+
+The boostrapper can be configured to run only certain booters or phases of booters


boostrapper -> bootstrapper

I'd also rephrase it a bit: ...can be configured to run specific booters, or boot phases...

kjdelisle · 2018-02-23T19:34:04Z

pages/en/lb4/Booting-an-Application.md

+by passing in `BootExecOptions`. **This is experimental and subject to change. Hence,
+this functionality is not exposed when calling `boot()` via `BootMixin`**.
+
+To use `BootExecOptions` you must directly call `bootstrapper.boot()` instead of `app.boot()`.


Need a comma after BootExecOptions.

"To use BootExecOptions, you must..."
(I can't use the backticks in the example, messes up the formatting.)

kjdelisle · 2018-02-23T19:35:03Z

pages/en/lb4/Concepts.md

+* [**Server**](Server.html): Represents implementation for inbound transports and/or protocols such as REST over http, gRPC over http2, and graphQL over https. It typically listens for requests on a specific port, handle them, and return appropriate responses.
+* [**Context**](Context.html): An abstraction of all state and dependencies in your application, that LoopBack uses to “manage” everything. It's a global registry for everything in your app (configurations, state, dependencies, classes, and so on).
+* [**Dependency Injection**](Dependency-injection.html): Technique that separates the construction of dependencies of a class or function from its behavior, to keep the code loosely coupled.
+* [**Booting an Application**](Booting-an-Application.html): A convention based


convention-based

dhmlau · 2018-02-23T21:26:13Z

+1 on splitting into 2 pages or at least 2 sections.
I wonder if the split is MVP. But the other argument is we might as well get it all fixed at one time, rather than going back again when we have time.

Please feel free to create separate issue to track that. I don't think it should be a blocker to land this PR.

b-admike · 2018-02-27T15:49:08Z

pages/en/lb4/Booting-an-Application.md

+
+#### configure
+
+Used to configure the `Booter` with it's default options.


it's -> its

b-admike · 2018-02-27T15:50:20Z

pages/en/lb4/Booting-an-Application.md

+### Example
+
+```ts
+class MyApp extends BootMixin(Application) {}


can we show the imports here?

shimks

Some tables are broken, but once that's been fixed,

shimks · 2018-02-27T16:44:54Z

pages/en/lb4/Booting-an-Application.md

+
+| Options      | Type                | Default              | Description                                                                                                   |
+| ------------ | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `dirs`       | `string | string[]` | `['controllers']`    | Paths relative to projectRoot to look in for Controller artifacts                                             |


The table is broken here

shimks · 2018-02-27T16:45:14Z

pages/en/lb4/Booting-an-Application.md

+
+| Options      | Type                | Default              | Description                                                                                                   |
+| ------------ | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `dirs`       | `string | string[]` | `['repositories']`   | Paths relative to projectRoot to look in for Repository artifacts                                             |


Broken here as well

b-admike

+1 for Kyu's comments, LGTM otherwise

virkt25 · 2018-02-28T05:42:22Z

Good catch @shimks. Used | in the table without escaping it. Weird that the backticks don't escape it automatically.

virkt25 requested review from raymondfeng, bajtos, kjdelisle, jannyHou, b-admike, shimks and dhmlau February 21, 2018 06:56

virkt25 requested a review from bschrammIBM as a code owner February 21, 2018 06:56

virkt25 added the needs-priority label Feb 21, 2018

dhmlau reviewed Feb 22, 2018

View reviewed changes

shimks reviewed Feb 22, 2018

View reviewed changes

kjdelisle suggested changes Feb 23, 2018

View reviewed changes

virkt25 force-pushed the docs/boot branch from f1cd7e0 to 9d529b2 Compare February 27, 2018 07:25

b-admike reviewed Feb 27, 2018

View reviewed changes

shimks approved these changes Feb 27, 2018

View reviewed changes

b-admike approved these changes Feb 27, 2018

View reviewed changes

bschrammIBM approved these changes Feb 27, 2018

View reviewed changes

kjdelisle approved these changes Feb 28, 2018

View reviewed changes

docs(boot): Docs for @loopback/boot

b8bbad2

virkt25 force-pushed the docs/boot branch from 72723dd to b8bbad2 Compare February 28, 2018 15:26

virkt25 merged commit 7ccfb55 into gh-pages Feb 28, 2018

virkt25 deleted the docs/boot branch February 28, 2018 15:32

virkt25 removed the needs-priority label Feb 28, 2018

shimks mentioned this pull request Mar 15, 2018

Docs/finish migration from loopback.io loopbackio/loopback-next#1141

Merged

6 tasks


		## BootComponent

		This component is added to a Application by `BootMixin` if used. The Component:


		## Usage: @loopback/cli

		New projects generated using `@loopback/cli` or `lb4` are automatically enabled


		### app.booters()

		A convenience method manually bind `Booters`. You can pass any number of `Booter`


		## Bootstrapper

		A Class that acts as the "manager" for Booters. The Boostrapper is designed to be


		#### configure

		Used to configure the `Booter` with it's default options.

docs(boot): Docs for @loopback/boot #631

docs(boot): Docs for @loopback/boot #631

Conversation

virkt25 commented Feb 21, 2018

dhmlau left a 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

shimks left a comment • edited Loading

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

virkt25 commented Feb 23, 2018

dhmlau commented Feb 23, 2018

kjdelisle left a 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

dhmlau commented Feb 23, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shimks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

b-admike left a comment

Choose a reason for hiding this comment

virkt25 commented Feb 28, 2018

shimks left a comment •

edited

Loading