chore: expand and polish cdk docs #7675

jelbourn · 2017-10-10T02:50:03Z

Add JsDocs where missing
Adds and polishes overviews for main cdk subpackages
Tweaks dgeni to disambiguate between material and cdk output (e.g. with "table").
Tweaks markdown process to disambiguate between material and cdk output
Fix an issue where method return types were missing from all api docs
Correct some any property types in cdk/stepper
Correct table trackBy JsDoc being omitted because it was on the setter

jelbourn · 2017-10-10T02:51:06Z

tools/gulp/tasks/docs.ts

+});
+
+/** Generates html files from the markdown overviews and guides. */
+task('markdown-docs-cdk', () => {


@crisbeto or @devversion I know this is wrong but I don't know the right way to fix it

(disambiguating material and cdk output)

Yeah I see. Would have been nice to name the other task markdown-docs-material or something, but this is not really a priority right now.

Not sure a better way to resolve this right now, left a TODO

devversion · 2017-10-10T06:26:05Z

src/cdk/bidi/dir.ts

@@ -27,7 +28,7 @@ import {Direction, Directionality} from './directionality';
  exportAs: 'dir',
 })
 export class Dir implements Directionality {
-  /** Layout direction of the element. */
+  /** @docs-private */
  _dir: Direction = 'ltr';


Shouldn't be needed since its prefixed with an underscore.

devversion · 2017-10-10T06:26:58Z

src/cdk/layout/layout.md

+
+#### React to changes to the viewport
+The `observe` method is used to get an observable stream that will emit whenever one of the given
+media queries would have a different results.


Not too sure, would have different results (dropping the a)?

Done (dropped the "s")

devversion · 2017-10-10T06:38:05Z

tools/dgeni/templates/componentGroup.template.html

@@ -21,7 +21,7 @@

 <div class="docs-api">
  <h2>
-    API reference for Angular Material {$ doc.name $}
+    API reference for Angular {$ doc.packageDisplayName $} {$ doc.displayName $}
  </h2>

  <p class="docs-api-module-import">


We should fix the import statement here as well. We can just use doc.packageName for the imports package name.

mmalerba · 2017-10-10T17:18:27Z

src/cdk/a11y/a11y.md

@@ -0,0 +1,90 @@
+The `a11y` package provides a number of tools to improve accessibility, described below.


FocusMonitor as well

I'll add that in a follow-up PR

josephperrott · 2017-10-10T17:03:46Z

src/cdk/a11y/a11y.md

+* Create a `@ViewChildren` query for the options being managed.
+* Initialize the `ListKeyManager`, passing in the options.
+* Forward keyboard events from the managed component to the `ListKeyManager`
+


Add . at end of sentence?

josephperrott · 2017-10-10T17:07:58Z

src/cdk/a11y/interactivity-checker.ts

- * supported.
- */
+
+// The InteractivityChecker leans heavily on the ally.js accessibility utilities.


a11y.ts instead of .js?

With ally.js is a library meant, not a source file inside of Material. https://allyjs.io/

josephperrott · 2017-10-10T17:19:22Z

src/cdk/layout/layout.md

+The built-in breakpoints based on [Google's Material Design
+specification](https://material.io/guidelines/layout/responsive-ui.html#responsive-ui-breakpoints).
+The available values are:
+* Handset


Should these be styled as code? i.e. Handset

I think it's fine without the code style

josephperrott · 2017-10-10T17:20:07Z

src/cdk/layout/layout.md

+
+
+### MediaMatcher
+`MediaMatcher` is a lower-level utility that wraps the native `matcheMedia`. This service normalizes


matchMedia, extra e

josephperrott · 2017-10-10T17:21:34Z

src/cdk/overlay/position/connected-position-strategy.ts

  attach(overlayRef: OverlayRef): void {
    this._overlayRef = overlayRef;
    this._pane = overlayRef.overlayElement;
    this._resizeSubscription.unsubscribe();
    this._resizeSubscription = this._viewportRuler.change().subscribe(() => this.apply());
  }

-  /** Performs any cleanup after the element is destroyed. */
+  /** Disposes all resources used by the posiiton strategy. */


josephperrott · 2017-10-10T17:22:29Z

src/cdk/overlay/position/connected-position.ts

+  constructor(
+      /** The position used as a result of this change. */
+      public connectionPair: ConnectionPositionPair,
+      /** @docs-private */


If this is @docs-private should it be _scrollableViewProperties

Can't rename b/c someone in google is using it

josephperrott · 2017-10-10T17:24:13Z

src/cdk/stepper/step-label.ts

@@ -12,5 +12,5 @@ import {Directive, TemplateRef} from '@angular/core';
  selector: '[cdkStepLabel]',
 })
 export class CdkStepLabel {
-  constructor(public template: TemplateRef<any>) { }
+  constructor(/** @docs-private */ public template: TemplateRef<any>) { }


_template?

Avoiding rename in case someone is using it

crisbeto · 2017-10-10T18:18:02Z

src/cdk/a11y/a11y.md

+}
+```
+
+#### Wrapping


Add a short paragraph like this for typeahead?

Can add in a follow-up PR.

crisbeto · 2017-10-10T18:18:20Z

src/cdk/a11y/a11y.md

+``` 
+
+#### Types of key managers
+There are two varieties of `ListKeyManager`: `FocusKeyManager` and `ActiveDescendantKeyManager`.


Comma instead of colon after the ListKeyManager.

crisbeto · 2017-10-10T18:18:31Z

src/cdk/a11y/a11y.md

+There are two varieties of `ListKeyManager`: `FocusKeyManager` and `ActiveDescendantKeyManager`.
+
+##### FocusKeyManager
+Used when options will directly recieve browser focus. Each item managed must implement the


recieve -> receive

crisbeto · 2017-10-10T18:19:20Z

src/cdk/a11y/a11y.md

+##### ActiveDescendantKeyManager
+Used when options will be marked as active via `aria-activedescendant`. 
+Each item managed must implement the
+`FocusableOption` interface:


This should be Highlightable. Also might be worth noting that each item requires an id and that id should be bound to the host.

crisbeto · 2017-10-10T18:21:27Z

src/cdk/bidi/directionality.ts

  readonly value: Direction = 'ltr';
+
+  /** Steam that emits whenever the 'ltr' / 'rtl' state changes. */


Steam -> Stream

crisbeto · 2017-10-10T18:22:06Z

src/cdk/layout/breakpoints-observer.ts

+  /**
+   * Whether one or more media queries match the current viewport size.
+   * @param value One or more media queries to check.
+   * @returns Whether any of the media queries matches.


matches -> matched

Done ("match")

crisbeto · 2017-10-10T18:25:39Z

src/cdk/stepper/stepper.md

@@ -0,0 +1,59 @@
+CDK stepper provides a foundation upon which more concrete stepper varities can be built upon. A


The sentence has one too many "upon"-s.

crisbeto · 2017-10-10T18:26:34Z

src/cdk/stepper/stepper.md

+
+### Behavior captured by CdkStepper
+The base CDK version of the stepper primarily manages which step is active. This includes handling
+keyboard interactions and exposing an API for advancing or rewinding through th workflow.


crisbeto · 2017-10-10T18:27:13Z

src/cdk/stepper/stepper.md

+
+#### Linear stepper
+A stepper marked as `linear` requires the user to complete previous steps before proceeding
+to following steps. For each step, the `stepControl` attribute can be set to the top level


I think the to following steps is redundant.

crisbeto · 2017-10-10T18:27:52Z

src/cdk/stepper/stepper.md

+### Types of steps
+
+#### Optional step
+If completion of a step in linear stepper is not required, then the `optional` attribute can be set


...in a linear stepper

* Add JsDocs where missing * Adds and polishes overviews for main cdk subpackages * Tweaks dgeni to disambiguate between material and cdk output (e.g. with "table"). * Tweaks markdown process to disambiguate between material and cdk output * Fix an issue where method return types were missing from _all_ api docs * Correct some `any` property types in cdk/stepper * Correct table trackBy JsDoc being omitted because it was on the setter

crisbeto

LGTM

angular-automatic-lock-bot · 2019-09-08T15:01:56Z

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.}

jelbourn requested review from crisbeto, devversion, josephperrott and mmalerba October 10, 2017 02:50

jelbourn requested a review from andrewseguin as a code owner October 10, 2017 02:50

googlebot added the cla: yes PR author has agreed to Google's Contributor License Agreement label Oct 10, 2017

jelbourn added docs This issue is related to documentation pr: needs review labels Oct 10, 2017

jelbourn commented Oct 10, 2017

View reviewed changes

jelbourn mentioned this pull request Oct 10, 2017

Disambiguate between material and cdk docs angular/material.angular.io#286

Merged

devversion reviewed Oct 10, 2017

View reviewed changes

jelbourn force-pushed the cdk-docs branch from b67ecaa to 9212121 Compare October 10, 2017 14:10

mmalerba reviewed Oct 10, 2017

View reviewed changes

josephperrott reviewed Oct 10, 2017

View reviewed changes

crisbeto reviewed Oct 10, 2017

View reviewed changes

jelbourn added the P1 Impacts a large percentage of users; if a workaround exists it is partial or overly painful label Oct 25, 2017

jelbourn force-pushed the cdk-docs branch from 9212121 to f16e5b2 Compare October 26, 2017 02:01

crisbeto approved these changes Oct 26, 2017

View reviewed changes

crisbeto added pr: lgtm action: merge The PR is ready for merge by the caretaker and removed pr: needs review labels Oct 26, 2017

mmalerba merged commit 0f2c272 into angular:master Oct 27, 2017

jelbourn deleted the cdk-docs branch April 2, 2018 22:30

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

		@@ -0,0 +1,90 @@
		The `a11y` package provides a number of tools to improve accessibility, described below.



		### MediaMatcher
		`MediaMatcher` is a lower-level utility that wraps the native `matcheMedia`. This service normalizes

		readonly value: Direction = 'ltr';

		/** Steam that emits whenever the 'ltr' / 'rtl' state changes. */

		@@ -0,0 +1,59 @@
		CDK stepper provides a foundation upon which more concrete stepper varities can be built upon. A

chore: expand and polish cdk docs #7675

chore: expand and polish cdk docs #7675

Uh oh!

Conversation

jelbourn commented Oct 10, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!