From a212fb4dde64c8f8ab86f11e96e373cecfcb1405 Mon Sep 17 00:00:00 2001 From: mgechev Date: Wed, 4 May 2022 17:22:38 -0700 Subject: [PATCH] docs: update the Angular DevTools auto-generated READMEs (#45884) Replace the auto-generated READMEs in the different Angular DevTools submodules with brief descriptions. PR Close #45884 --- .../projects/ng-devtools-backend/README.md | 25 ++------------- devtools/projects/ng-devtools/README.md | 25 ++------------- devtools/projects/protocol/README.md | 31 +++++++------------ devtools/projects/shared-utils/README.md | 26 ++-------------- 4 files changed, 18 insertions(+), 89 deletions(-) diff --git a/devtools/projects/ng-devtools-backend/README.md b/devtools/projects/ng-devtools-backend/README.md index de5c5260cbe..e02cc1482f8 100644 --- a/devtools/projects/ng-devtools-backend/README.md +++ b/devtools/projects/ng-devtools-backend/README.md @@ -1,24 +1,3 @@ -# NgDevtoolsBackend +# Angular DevTools Backend -This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 8.0.0. - -## Code scaffolding - -Run `ng generate component component-name --project ng-devtools-backend` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ng-devtools-backend`. -> Note: Don't forget to add `--project ng-devtools-backend` or else it will be added to the default project in your `angular.json` file. - -## Build - -Run `ng build ng-devtools-backend` to build the project. The build artifacts will be stored in the `dist/` directory. - -## Publishing - -After building your library with `ng build ng-devtools-backend`, go to the dist folder `cd dist/ng-devtools-backend` and run `npm publish`. - -## Running unit tests - -Run `ng test ng-devtools-backend` to execute the unit tests via [Karma](https://karma-runner.github.io). - -## Further help - -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/main/README.md). +This directory contains the "backend" of Angular DevTools. This module interacts with the framework debugging APIs and responses to requests from the Angular DevTools extension. diff --git a/devtools/projects/ng-devtools/README.md b/devtools/projects/ng-devtools/README.md index 37bc538c1b4..5a94871c793 100644 --- a/devtools/projects/ng-devtools/README.md +++ b/devtools/projects/ng-devtools/README.md @@ -1,24 +1,3 @@ -# ng-devtools +# Angular DevTools UI -This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 9.0.0-rc.5. - -## Code scaffolding - -Run `ng generate component component-name --project ng-devtools` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ng-devtools`. -> Note: Don't forget to add `--project ng-devtools` or else it will be added to the default project in your `angular.json` file. - -## Build - -Run `ng build ng-devtools` to build the project. The build artifacts will be stored in the `dist/` directory. - -## Publishing - -After building your library with `ng build ng-devtools`, go to the dist folder `cd dist/ng-devtools` and run `npm publish`. - -## Running unit tests - -Run `ng test ng-devtools` to execute the unit tests via [Karma](https://karma-runner.github.io). - -## Further help - -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/main/README.md). +This module exports the Angular DevTools component. We render the `DevToolsComponent` within an Angular application running in Chrome or Firefox DevTools. This module of the application communicates with the Angular DevTools "backend". diff --git a/devtools/projects/protocol/README.md b/devtools/projects/protocol/README.md index 03ae622be01..fd0be2e931b 100644 --- a/devtools/projects/protocol/README.md +++ b/devtools/projects/protocol/README.md @@ -1,24 +1,17 @@ -# Protocol +# Angular DevTools Communication Protocol -This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 9.0.0-rc.5. +Angular DevTools injects scripts in the user application page that interact with the framework debugging APIs. The injected scripts interact with the extension via message passing using a statically typed protocol. -## Code scaffolding +This subdirectory contains: +- Declaration of a statically typed message bus +- Implementation of priority aware message bus +- Interfaces that declare the messages exchanged between the extension and the page -Run `ng generate component component-name --project protocol` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project protocol`. -> Note: Don't forget to add `--project protocol` or else it will be added to the default project in your `angular.json` file. +We use the `PriorityAwareMessageBus` to ensure that certain messages have higher priority than others. Because of the asynchronous nature of the property exchange there's a risk that a message response may overwrite the result from a more recent response. -## Build +An example is: +1. We request the state of the component tree +1. We update the state +1. We request the state of the properties of a particular component -Run `ng build protocol` to build the project. The build artifacts will be stored in the `dist/` directory. - -## Publishing - -After building your library with `ng build protocol`, go to the dist folder `cd dist/protocol` and run `npm publish`. - -## Running unit tests - -Run `ng test protocol` to execute the unit tests via [Karma](https://karma-runner.github.io). - -## Further help - -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/main/README.md). +We don't have guarantees that the response of 1. will arrive before the response of 3. Often the response of 1. is larger and might be delivered after 3. In such a case, it may contain the application state prior to the update and override the state update we received from 3. diff --git a/devtools/projects/shared-utils/README.md b/devtools/projects/shared-utils/README.md index c795428c013..0c151a743e1 100644 --- a/devtools/projects/shared-utils/README.md +++ b/devtools/projects/shared-utils/README.md @@ -1,25 +1,3 @@ -# SharedUtils +# Shared Utilities -This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 8.0.0. - -## Code scaffolding - -Run `ng generate component component-name --project shared-utils` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project shared-utils`. - -> Note: Don't forget to add `--project shared-utils` or else it will be added to the default project in your `angular.json` file. - -## Build - -Run `ng build shared-utils` to build the project. The build artifacts will be stored in the `dist/` directory. - -## Publishing - -After building your library with `ng build shared-utils`, go to the dist folder `cd dist/shared-utils` and run `npm publish`. - -## Running unit tests - -Run `ng test shared-utils` to execute the unit tests via [Karma](https://karma-runner.github.io). - -## Further help - -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/main/README.md). +This directory contains shared utilities between different Angular DevTools modules.