From 2b77d52061b2107bb100643bd7072d4cb61de55a Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Tue, 1 Mar 2016 19:24:30 -0500 Subject: [PATCH] docs(API): clean up API docs --- ionic/components/action-sheet/action-sheet.ts | 14 +++---- ionic/components/alert/alert.ts | 10 ++--- ionic/components/app/id.ts | 4 +- ionic/components/button/button.ts | 37 +++++++++-------- ionic/components/checkbox/checkbox.ts | 10 +++-- ionic/components/icon/icon.ts | 6 +-- ionic/components/label/label.ts | 17 +++++--- ionic/components/menu/menu-controller.ts | 2 +- ionic/components/navbar/navbar.ts | 13 +++--- .../show-hide-when/show-hide-when.ts | 41 ++++++++++++++++++- ionic/config/config.ts | 9 ++-- ionic/util/events.ts | 3 +- ionic/util/keyboard.ts | 2 +- 13 files changed, 108 insertions(+), 60 deletions(-) diff --git a/ionic/components/action-sheet/action-sheet.ts b/ionic/components/action-sheet/action-sheet.ts index eff9962746..44af5bb44b 100644 --- a/ionic/components/action-sheet/action-sheet.ts +++ b/ionic/components/action-sheet/action-sheet.ts @@ -16,9 +16,9 @@ import {ViewController} from '../nav/view-controller'; * An Action Sheet is a dialog that lets the user choose from a set of * options. It appears on top of the app's content, and must be manually * dismissed by the user before they can resume interaction with the app. - * Dangerous (destructive) options are made obvious. There are easy + * Dangerous (destructive) options are made obvious in `ios` mode. There are easy * ways to cancel out of the action sheet, such as tapping the backdrop or - * hitting the escape key on desktop. + * hitting the escape key on desktop. * * An action sheet is created from an array of `buttons`, with each button * including properties for its `text`, and optionally a `handler` and `role`. @@ -26,16 +26,16 @@ import {ViewController} from '../nav/view-controller'; * action sheet can also optionally have a `title` and a `subTitle`. * * A button's `role` property can either be `destructive` or `cancel`. Buttons - * without a role property will have a default look for its platform. Buttons + * without a role property will have the default look for the platform. Buttons * with the `cancel` role will always load as the bottom button, no matter where - * it shows up in the array. All other buttons will show up in the order they + * they are in the array. All other buttons will be displayed in the order they * have been added to the `buttons` array. Note: We recommend that `destructive` - * buttons show be the first button in the array, making it the button on top. + * buttons are always the first button in the array, making them the top button. * Additionally, if the action sheet is dismissed by tapping the backdrop, then * it will fire the handler from the button with the cancel role. * - * Its shorthand is to add all the action sheet's options from within the - * `ActionSheet.create(opts)` first argument. Otherwise the action sheet's + * You can pass all of the action sheet's options in the first argument of + * the create method: `ActionSheet.create(opts)`. Otherwise the action sheet's * instance has methods to add options, like `setTitle()` or `addButton()`. * * @usage diff --git a/ionic/components/alert/alert.ts b/ionic/components/alert/alert.ts index 8743b24936..e8e4aee1b2 100644 --- a/ionic/components/alert/alert.ts +++ b/ionic/components/alert/alert.ts @@ -12,8 +12,8 @@ import {ViewController} from '../nav/view-controller'; /** * @name Alert * @description - * An Alert is a dialog that presents users with either information, or used - * to receive information from the user using inputs. An alert appears on top + * An Alert is a dialog that presents users with information or collects + * information from the user using inputs. An alert appears on top * of the app's content, and must be manually dismissed by the user before * they can resume interaction with the app. * @@ -31,11 +31,11 @@ import {ViewController} from '../nav/view-controller'; * by tapping the backdrop, then it will fire the handler from the button * with a cancel role. * - * Alerts can also include inputs whos data can be passed back to the app. + * Alerts can also include inputs whose data can be passed back to the app. * Inputs can be used to prompt users for information. * - * Its shorthand is to add all the alert's options from within the - * `Alert.create(opts)` first argument. Otherwise the alert's instance + * You can pass all of the alert's options in the first argument of + * the create method: `Alert.create(opts)`. Otherwise the alert's instance * has methods to add options, such as `setTitle()` or `addButton()`. * * @usage diff --git a/ionic/components/app/id.ts b/ionic/components/app/id.ts index 0a1b453510..4729ad0e73 100644 --- a/ionic/components/app/id.ts +++ b/ionic/components/app/id.ts @@ -5,9 +5,9 @@ import {IonicApp} from './app'; /** * @name Id * @description - * IdRef is an easy way to identify unique components in an app and access them + * The `id` attribute is an easy way to identify unique components in an app and access them * no matter where in the UI hierarchy you are. For example, this makes toggling - * a global side menu feasible from any place in the application. + * a global side menu possible from any place in the application. * * See the [Menu section](http://ionicframework.com/docs/v2/components/#menus) of * the Component docs for an example of how Menus rely on ID's. diff --git a/ionic/components/button/button.ts b/ionic/components/button/button.ts index 14ec44ffb1..02cad24786 100644 --- a/ionic/components/button/button.ts +++ b/ionic/components/button/button.ts @@ -7,26 +7,29 @@ import {Toolbar} from '../toolbar/toolbar'; /** * @name Button * @module ionic - * @property [outline] - for an unfilled outline button - * @property [clear] - for a transparent button that only shows text and icons - * @property [round] - for a button with rounded corners - * @property [block] - for a block button that fills it's parent container - * @property [full] - for a full width button - * @property [small] - sets button size to small - * @property [large] - sets button size to large - * @property [disabled] - disables the button - * @property [fab] - for a floating action button - * @property [fab-left] - position a fab button to the left - * @property [fab-right] - position a fab button to the right - * @property [fab-center] - position a fab button towards the center - * @property [fab-top] - position a fab button towards the top - * @property [fab-bottom] - position a fab button towards the bottom - * @property [color] - Dynamically set which color attribute this button should use. + * * @description - * Buttons are simple components in Ionic, can consist of text, an icon, or both, and can be enhanced with a wide range of attributes. + * Buttons are simple components in Ionic. They can consist of text and icons + * and be enhanced by a wide range of attributes. + * + * @property [outline] - A transparent button with a border. + * @property [clear] - A transparent button without a border. + * @property [round] - A button with rounded corners. + * @property [block] - A button that fills its parent container with a border-radius. + * @property [full] - A button that fills its parent container without a border-radius or borders on the left/right. + * @property [small] - A button with size small. + * @property [large] - A button with size large. + * @property [disabled] - A disabled button. + * @property [fab] - A floating action button. + * @property [fab-left] - Position a fab button to the left. + * @property [fab-right] - Position a fab button to the right. + * @property [fab-center] - Position a fab button towards the center. + * @property [fab-top] - Position a fab button towards the top. + * @property [fab-bottom] - Position a fab button towards the bottom. + * @property [color] - Dynamically set which color attribute this button should use. + * * @demo /docs/v2/demos/button/ * @see {@link /docs/v2/components#buttons Button Component Docs} - */ @Component({ selector: 'button:not([ion-item]),[button]', diff --git a/ionic/components/checkbox/checkbox.ts b/ionic/components/checkbox/checkbox.ts index bcb2d8dad1..ca7d6d6c28 100644 --- a/ionic/components/checkbox/checkbox.ts +++ b/ionic/components/checkbox/checkbox.ts @@ -10,9 +10,12 @@ const CHECKBOX_VALUE_ACCESSOR = new Provider( /** - * The checkbox is no different than the HTML checkbox input, except - * it's styled accordingly to the the platform and design mode, such - * as iOS or Material Design. + * @name Checkbox + * @module ionic + * + * @description + * The Checkbox is a simple component styled based on the mode. It can be + * placed in an `ion-item` or used as a stand-alone checkbox. * * See the [Angular 2 Docs](https://angular.io/docs/ts/latest/guide/forms.html) * for more info on forms and inputs. @@ -40,6 +43,7 @@ const CHECKBOX_VALUE_ACCESSOR = new Provider( * * * ``` + * * @demo /docs/v2/demos/checkbox/ * @see {@link /docs/v2/components#checkbox Checkbox Component Docs} */ diff --git a/ionic/components/icon/icon.ts b/ionic/components/icon/icon.ts index 45b99af1b5..540299a217 100644 --- a/ionic/components/icon/icon.ts +++ b/ionic/components/icon/icon.ts @@ -10,12 +10,12 @@ import {Config} from '../../config/config'; * For a full list of available icons, check out the * [Ionicons resource docs](../../../../resources/ionicons). * - * One feature of Ionicons is that when icon names are set, the actual icon + * One feature of Ionicons in Ionic is when icon names are set, the actual icon * which is rendered can change slightly depending on the mode the app is * running from. For example, by setting the icon name of `alarm`, on iOS the * icon will automatically apply `ios-alarm`, and on Material Design it will - * automatically apply `md-alarm`. This allow the developer to write the - * markup once, and let Ionic automatically apply the appropriate icon. + * automatically apply `md-alarm`. This allows the developer to write the + * markup once while Ionic applies the appropriate icon based on the mode. * * @usage * ```html diff --git a/ionic/components/label/label.ts b/ionic/components/label/label.ts index bef41feb2c..280c4d8366 100644 --- a/ionic/components/label/label.ts +++ b/ionic/components/label/label.ts @@ -4,10 +4,8 @@ import {Directive, ElementRef, Renderer, Input, Optional, Attribute} from 'angul /** * @name Label * @description - * Labels describe the data that the user should enter in to an input - * element. You can give `ion-label` attributes to tell it how to - * handle its display type, which is especially useful for an - * `ion-item` which contains a text input. + * Labels are placed inside of an `ion-item` element and can be used + * to describe an `ion-input`, `ion-toggle`, `ion-checkbox`, and more. * * @property [fixed] - a persistant label that sits next the the input * @property [floating] - a label that will float about the input if the input is empty of looses focus @@ -22,7 +20,7 @@ import {Directive, ElementRef, Renderer, Input, Optional, Attribute} from 'angul * * * - * Website + * Website * * * @@ -36,6 +34,15 @@ import {Directive, ElementRef, Renderer, Input, Optional, Attribute} from 'angul * * * + * + * Toggle + * + * + * + * + * Checkbox + * + * * ``` * * @demo /docs/v2/demos/label/ diff --git a/ionic/components/menu/menu-controller.ts b/ionic/components/menu/menu-controller.ts index 161ae339fc..df22a92bd3 100644 --- a/ionic/components/menu/menu-controller.ts +++ b/ionic/components/menu/menu-controller.ts @@ -8,7 +8,7 @@ import {MenuType} from './menu-types'; * _For basic Menu usage, see the [Menu section](../../../../components/#menus) * of the Component docs._ * - * Menu is a side-menu interface that can be dragged out or toggled to open or closed. + * Menu is a side-menu interface that can be dragged and toggled to open or close. * An Ionic app can have numerous menus, all of which can be controlled within * template HTML, or programmatically. * diff --git a/ionic/components/navbar/navbar.ts b/ionic/components/navbar/navbar.ts index 4774ec9fd3..4f4dce9aed 100644 --- a/ionic/components/navbar/navbar.ts +++ b/ionic/components/navbar/navbar.ts @@ -63,17 +63,14 @@ class ToolbarBackground { * @name Navbar * @description * Navbar is a global level toolbar that gets updated every time a page gets - * loaded. You can pass the navbar a `ion-title` or any number of buttons. + * loaded. You can pass the navbar an `ion-title`, any number of buttons, a segment, or a searchbar. * * @usage * ```html * - * - * - * - * + * * * * Page Title @@ -81,7 +78,7 @@ class ToolbarBackground { * * * * * diff --git a/ionic/components/show-hide-when/show-hide-when.ts b/ionic/components/show-hide-when/show-hide-when.ts index b655369890..65b5c68111 100644 --- a/ionic/components/show-hide-when/show-hide-when.ts +++ b/ionic/components/show-hide-when/show-hide-when.ts @@ -65,7 +65,25 @@ export class DisplayWhen { * Complements the [hideWhen attribute](../HideWhen). * @usage * ```html - *
I am only visible on iOS!
+ *
+ * I am visible on Android! + *
+ * + *
+ * I am visible on iOS! + *
+ * + *
+ * I am visible on Android and iOS! + *
+ * + *
+ * I am visible on Portrait! + *
+ * + *
+ * I am visible on Landscape! + *
* ``` * @demo /docs/v2/demos/show-when/ * @see {@link ../HideWhen HideWhen API Docs} @@ -103,8 +121,27 @@ export class ShowWhen extends DisplayWhen { * Complements the [showWhen attribute](../ShowWhen). * @usage * ```html - *
I am hidden on Android!
+ *
+ * I am hidden on Android! + *
+ * + *
+ * I am hidden on iOS! + *
+ * + *
+ * I am hidden on Android and iOS! + *
+ * + *
+ * I am hidden on Portrait! + *
+ * + *
+ * I am hidden on Landscape! + *
* ``` + * * @demo /docs/v2/demos/hide-when/ * @see {@link ../ShowWhen ShowWhen API Docs} */ diff --git a/ionic/config/config.ts b/ionic/config/config.ts index 0f11e5e377..639a9ca765 100644 --- a/ionic/config/config.ts +++ b/ionic/config/config.ts @@ -13,7 +13,8 @@ import {isObject, isDefined, isFunction, isArray} from '../util/util'; * @name Config * @demo /docs/v2/demos/config/ * @description - * Config lets you change multiple or a single value in an apps mode configuration. Things such as tab placement, icon changes, and view animations can be set here. + * The Config lets you configure your entire app or specific platforms. + * You can set the tab placement, icon mode, animations, and more here. * * ```ts * @App({ @@ -29,7 +30,7 @@ import {isObject, isDefined, isFunction, isArray} from '../util/util'; * }) * ``` * - * Or change the whole mode + * To change the mode to always use Material Design (md). * * ```ts * @App({ @@ -40,7 +41,7 @@ import {isObject, isDefined, isFunction, isArray} from '../util/util'; * }) * ``` * - * Config can be overwritting at multiple levels, allowing deeper configuration. Taking the example from earlier, we can override any setting we want based on a platform. + * Config can be overwritten at multiple levels allowing for more configuration. Taking the example from earlier, we can override any setting we want based on a platform. * ```ts * @App({ * template: `` @@ -63,8 +64,6 @@ import {isObject, isDefined, isFunction, isArray} from '../util/util'; * * ``` * - * The property will override anything else set in the apps. - * * The last way we could configure is through URL query strings. This is useful for testing while in the browser. * Simply add `?ionic=` to the url. * diff --git a/ionic/util/events.ts b/ionic/util/events.ts index 3aa444ac21..413e4b459d 100644 --- a/ionic/util/events.ts +++ b/ionic/util/events.ts @@ -1,8 +1,9 @@ /** * @name Events * @description - * Events is a pub/sub style event system for sending and responding to application-level + * Events is a publish-subscribe style event system for sending and responding to application-level * events across your app. + * * @usage * ```ts * // first page (publish an event when a user is created) diff --git a/ionic/util/keyboard.ts b/ionic/util/keyboard.ts index 0d3c0bc558..7614041539 100644 --- a/ionic/util/keyboard.ts +++ b/ionic/util/keyboard.ts @@ -7,7 +7,7 @@ import {hasFocusedTextInput, raf, rafFrames} from './dom'; /** * @name Keyboard * @description - * The `Keyboard` class allows you to work with the keyboard events provide by the Ionic keyboard plugin. + * The `Keyboard` class allows you to work with the keyboard events provided by the Ionic keyboard plugin. * * @usage * ```ts