honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(*): add `@publicModule` tags 

Initial set of tags to demonstrate the public docs filtering

Closes #988
This commit is contained in:
Peter Bacon Darwin 2015-03-17 19:22:13 +00:00 committed by Misko Hevery
parent 8229d7edc2
commit 85799aa1a5
14 changed files with 302 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/dgeni-package/processors/processClassDocs.js
View File

@ -5,8 +5,10 @@ module.exports = function processClassDocs(log, getJSDocComment) {
return {
$runAfter: ['processModuleDocs'],
$runBefore: ['parsing-tags', 'generateDocsFromComments'],
ignorePrivateMembers: false,
$process: function(docs) {
var memberDocs = [];
var ignorePrivateMembers = this.ignorePrivateMembers;
_.forEach(docs, function(classDoc) {
if ( classDoc.docType === 'class' ) {
@ -15,6 +17,8 @@ module.exports = function processClassDocs(log, getJSDocComment) {
// Create a new doc for each member of the class
_.forEach(classDoc.elements, function(memberDoc) {
if (ignorePrivateMembers && memberDoc.name.literalToken.value.charAt(0) === '_') return;
classDoc.members.push(memberDoc);
memberDocs.push(memberDoc);
@ -22,6 +26,7 @@ module.exports = function processClassDocs(log, getJSDocComment) {
memberDoc.classDoc = classDoc;
memberDoc.name = memberDoc.name.literalToken.value;
if (memberDoc.commentBefore ) {
// If this export has a comment, remove it from the list of
// comments collected in the module

21
docs/dgeni-package/services/ExportTreeVisitor.js
View File

@ -17,8 +17,10 @@ module.exports = function ExportTreeVisitor(ParseTreeVisitor, log) {
ParseTreeVisitor.prototype.visitExportDeclaration.call(this, tree);
log.silly('exit', this.currentExport);
// We are exiting the export declaration - store the export object
this.exports.push(this.currentExport);
if(this.currentExport) {
// We are exiting the export declaration - store the export object
this.exports.push(this.currentExport);
}
this.currentExport = null;
},
@ -78,14 +80,15 @@ module.exports = function ExportTreeVisitor(ParseTreeVisitor, log) {
},
visitNamedExport: function(tree) {
if ( this.currentExport ) {
this.updateExport(tree);
this.currentExport = null;
// if ( this.currentExport ) {
// this.updateExport(tree);
this.currentExport.namedExport = tree;
this.currentExport.name = 'NAMED_EXPORT';
// TODO: work out this bit!!
// We need to cope with any export specifiers in the named export
}
// this.currentExport.namedExport = tree;
// this.currentExport.name = 'NAMED_EXPORT';
// // TODO: work out this bit!!
// // We need to cope with any export specifiers in the named export
// }
},
// TODO - if the export is an expression, find the thing that is being

4
docs/public-docs-package/index.js
View File

@ -10,6 +10,10 @@ module.exports = new Package('angular-public', [basePackage])
parseTagsProcessor.tagDefinitions.push({ name: 'publicModule' });
})
.config(function(processClassDocs) {
processClassDocs.ignorePrivateMembers = true;
})
// Configure file writing
.config(function(writeFilesProcessor) {
writeFilesProcessor.outputFolder = 'dist/public_docs';

310
modules/angular2/src/core/annotations/annotations.js vendored
View File

@ -4,148 +4,170 @@ import {ListWrapper, List} from 'angular2/src/facade/collection';
// type StringMap = {[idx: string]: string};
/**
* Directives allow you to attach behavior to the DOM elements.
*
* Directives allow you to attach behavior to the DOM elements.
*
* Directive is an abstract concept, instead use concrete directives such as: [Component], [Decorator] or [Viewport].
* @publicModule angular2/angular2
*/
@ABSTRACT()
export class Directive {
/**
* The CSS selector that triggers the instantiation of a directive.
*
* Angular only allows directives to trigger on CSS selectors that do not cross element boundaries.
* The CSS selector that triggers the instantiation of a directive.
*
* Angular only allows directives to trigger on CSS selectors that do not cross element boundaries.
* The supported selectors are:
*
*
* - `element-name` select by element name.
* - `.class` select by class name.
* - `[attribute]` select by attribute name.
* - `[attribute=value]` select by attribute name and value.
* - `:not(sub_selector)` select only if the element does not match the `sub_selector`.
*
*
* ## Example
*
*
* Suppose we have a directive with an `input[type=text]` selector.
*
*
* And the following HTML:
*
* <form>
* <input type="text">
* <input type="radio">
* <form>
*
* ```html
* <form>
* <input type="text">
* <input type="radio">
* <form>
* ```
*
* The directive would only be instantiated on the `<input type="text">` element.
*
*
*/
selector:string;
/**
* Enumerates the set of properties that accept data binding for a directive.
*
*
* The `bind` property defines a set of `directiveProperty` to `bindingProperty` key-value pairs:
*
*
* - `directiveProperty` specifies the component property where the value is written.
* - `bindingProperty` specifies the DOM property where the value is read from.
*
* You can include [Pipes] when specifying a `bindingProperty` to allow for data transformation and structural
* - `bindingProperty` specifies the DOM property where the value is read from.
*
* You can include [Pipes] when specifying a `bindingProperty` to allow for data transformation and structural
* change detection of the value.
*
*
* ## Syntax
* @Directive({
* bind: {
* 'directiveProperty1': 'bindingProperty1',
* 'directiveProperty2': 'bindingProperty2 | pipe1 | ...',
* ...
* }
* }
*
*
* ## Basic Property Binding:
*
* @Decorator({
* selector: '[tooltip]',
* bind: {
* 'tooltipText': 'tooltip'
* }
* })
* class Tooltip {
* set tooltipText(text) {
* // This will get called every time the 'tooltip' binding changes with the new value.
* }
* }
*
*
* ```
* @Directive({
* bind: {
* 'directiveProperty1': 'bindingProperty1',
* 'directiveProperty2': 'bindingProperty2 | pipe1 | ...',
* ...
* }
* }
* ```
*
*
* ## Basic Property Binding:
*
* ```
* @Decorator({
* selector: '[tooltip]',
* bind: {
* 'tooltipText': 'tooltip'
* }
* })
* class Tooltip {
* set tooltipText(text) {
* // This will get called every time the 'tooltip' binding changes with the new value.
* }
* }
* ```
*
* As used in this example:
*
* <div [tooltip]="someExpression">
*
* Whenever the `someExpression` expression changes, the `bind` declaration instructs Angular to update the
*
* ```html
* <div [tooltip]="someExpression">
* ```
*
* Whenever the `someExpression` expression changes, the `bind` declaration instructs Angular to update the
* `Tooltip`'s `tooltipText` property.
*
*
*
*
* Similarly in this example:
*
* <div tooltip="Some Text">
*
*
* ```html
* <div tooltip="Some Text">
* ```
*
* The `Tooltip`'s `tooltipText` property gets initialized to the `Some Text` literal.
*
*
* ## Bindings With Pipes:
*
* @Decorator({
* selector: '[class-set]',
* bind: {
* 'classChanges': 'classSet | keyValDiff'
* }
* })
* class ClassSet {
* set classChanges(changes:KeyValueChanges) {
* // This will get called every time the `class-set` expressions changes its structure.
* }
* }
*
*
*
* ## Bindings With Pipes:
*
* ```
* @Decorator({
* selector: '[class-set]',
* bind: {
* 'classChanges': 'classSet | keyValDiff'
* }
* })
* class ClassSet {
* set classChanges(changes:KeyValueChanges) {
* // This will get called every time the `class-set` expressions changes its structure.
* }
* }
* ```
*
* As used in this example:
* <div [class-set]="someExpression">
*
*
* ```html
* <div [class-set]="someExpression">
* ```
*
* In the above example, the `ClassSet` uses the `keyValDiff` [Pipe] for watching structural changes. This means that
* the `classChanges` setter gets invoked if the expression changes to a different reference, or if the
* the `classChanges` setter gets invoked if the expression changes to a different reference, or if the
* structure of the expression changes. (Shallow property watching of the object)
*
*
* NOTE: The `someExpression` can also contain its own [Pipe]s. In this case, the two pipes compose as if they were
* inlined.
*
*
*/
bind:any; // StringMap
/**
* Specifies which DOM events the directive listens to and what the action should be.
*
*
* The `event` property defines a set of `event` to `method` key-value pairs:
*
*
* - `event` specifies the DOM event that the directive listens to.
* - `onMethod` specifies the method to execute when the event occurs.
*
*
* - `onMethod` specifies the method to execute when the event occurs.
*
*
* ## Syntax
* @Directive({
* events: {
* 'event1': 'onMethod',
* ...
* }
* }
*
* ## Basic Event Binding:
*
* @Decorator({
* selector: 'input',
* event: {
* 'change': 'onChange'
* }
* })
* class InputDecorator {
* onChange(event:Event) {
* // invoked whenever the DOM element fires the 'change' event.
* }
* }
*
*
* ```
* @Directive({
* events: {
* 'event1': 'onMethod',
* ...
* }
* }
* ```
*
* ## Basic Event Binding:
*
* ```
* @Decorator({
* selector: 'input',
* event: {
* 'change': 'onChange'
* }
* })
* class InputDecorator {
* onChange(event:Event) {
* // invoked whenever the DOM element fires the 'change' event.
* }
* }
* ```
*
*/
events:any; // StringMap
@ -153,7 +175,7 @@ export class Directive {
* Specifies a set of lifecycle events in which the directive participates.
*/
lifecycle:any; //List<LifecycleEvent>
@CONST()
constructor({
selector,
@ -178,6 +200,9 @@ export class Directive {
}
}
/**
* @publicModule angular2/angular2
*/
export class Component extends Directive {
//TODO: vsavkin: uncomment it once the issue with defining fields in a sublass works
services:any; //List;
@ -208,6 +233,9 @@ export class Component extends Directive {
}
}
/**
* @publicModule angular2/angular2
*/
export class Decorator extends Directive {
compileChildren: boolean;
@CONST()
@ -235,6 +263,9 @@ export class Decorator extends Directive {
}
}
/**
* @publicModule angular2/angular2
*/
export class Viewport extends Directive {
@CONST()
constructor({
@ -261,47 +292,52 @@ export class Viewport extends Directive {
/**
* Specify that a directive should be notified whenever a [View] that contains it is destroyed.
*
*
* ## Example
*
* @Decorator({
* ...,
* lifecycle: [ onDestroy ]
* })
* class ClassSet implements OnDestroy {
* onDestroy() {
* // invoked to notify directive of the containing view destruction.
* }
* }
*
* ```
* @Decorator({
* ...,
* lifecycle: [ onDestroy ]
* })
* class ClassSet implements OnDestroy {
* onDestroy() {
* // invoked to notify directive of the containing view destruction.
* }
* }
* ```
* @publicModule angular2/angular2
*/
export const onDestroy = "onDestroy";
/**
* Specify that a directive should be notified when any of its bindings have changed.
*
* Specify that a directive should be notified when any of its bindings have changed.
*
* ## Example:
*
* @Decorator({
* selector: '[class-set]',
* bind: {
* 'propA': 'propA'
* 'propB': 'propB'
* }
* })
* class ClassSet {
* propA;
* propB;
*
* onChange(changes:{[idx: string, PropertyUpdate]}) {
* // This will get called after any of the properties have been updated.
* if (changes['propA']) {
* // if propA was updated
* }
* if (changes['propA']) {
* // if propB was updated
* }
* }
*
* ```
* @Decorator({
* selector: '[class-set]',
* bind: {
* 'propA': 'propA'
* 'propB': 'propB'
* }
* })
* class ClassSet {
* propA;
* propB;
* onChange(changes:{[idx: string, PropertyUpdate]}) {
* // This will get called after any of the properties have been updated.
* if (changes['propA']) {
* // if propA was updated
* }
* if (changes['propA']) {
* // if propB was updated
* }
* }
* }
* ```
* @publicModule angular2/angular2
*/
export const onChange = "onChange";

3
modules/angular2/src/core/annotations/template.js vendored
View File

@ -1,5 +1,8 @@
import {ABSTRACT, CONST, Type} from 'angular2/src/facade/lang';
/**
* @publicModule angular2/angular2
*/
export class Template {
url:any; //string;
inline:any; //string;

2
modules/angular2/src/core/annotations/visibility.js vendored
View File

@ -4,6 +4,7 @@ import {DependencyAnnotation} from 'angular2/di';
/**
* The directive can only be injected from the current element
* or from its parent.
* @publicModule angular2/angular2
*/
export class Parent extends DependencyAnnotation {
@CONST()
@ -15,6 +16,7 @@ export class Parent extends DependencyAnnotation {
/**
* The directive can only be injected from the current element
* or from its ancestor.
* @publicModule angular2/angular2
*/
export class Ancestor extends DependencyAnnotation {
@CONST()

142
modules/angular2/src/core/application.js vendored
View File

@ -118,102 +118,110 @@ function _createVmZone(givenReporter:Function): VmTurnZone {
}
/**
* Bootstrapping for Angular applications.
*
* You instantiate an Angular application by explicitly specifying a component to use as the root component for your
* Bootstrapping for Angular applications.
*
* You instantiate an Angular application by explicitly specifying a component to use as the root component for your
* application via the `bootstrap()` method.
*
*
* ## Simple Example
*
*
* Assuming this `index.html`:
* <html>
* <!-- load Angular script tags here. -->
* <body>
* <my-app>loading...</my-app>
* </body>
* </html>
*
*
* ```html
* <html>
* <!-- load Angular script tags here. -->
* <body>
* <my-app>loading...</my-app>
* </body>
* </html>
* ```
*
* An application is bootstrapped inside an existing browser DOM, typically `index.html`. Unlike Angular 1, Angular 2
* does not compile/process bindings in `index.html`. This is mainly for security reasons, as well as architectural
* changes in Angular 2. This means that `index.html` can safely be processed using server-side binding technologies,
* which may use double-curly `{{syntax}}` without collision from Angular 2 component double-curly `{{syntax}}`.
*
*
* We can use this script code:
* @Component({
* selector: 'my-app'
* })
* @Template({
* inline: 'Hello {{name}}!'
* })
* class MyApp {
* name:string;
*
* constructor() {
* this.name = 'World';
* }
* }
*
* main() {
* bootstrap(MyApp);
* }
*
* When the app developer invokes `bootstrap()` with the root component `MyApp` as its argument, Angular performs the
*
* ```
* @Component({
* selector: 'my-app'
* })
* @Template({
* inline: 'Hello {{name}}!'
* })
* class MyApp {
* name:string;
*
* constructor() {
* this.name = 'World';
* }
* }
*
* main() {
* bootstrap(MyApp);
* }
* ```
*
* When the app developer invokes `bootstrap()` with the root component `MyApp` as its argument, Angular performs the
* following tasks:
*
* 1. It uses the component's `selector` property to locate the DOM element which needs to be upgraded into
*
* 1. It uses the component's `selector` property to locate the DOM element which needs to be upgraded into
* the angular component.
* 2. It creates a new child injector (from the primordial injector) and configures the injector with the component's
* `services`. Optionally, you can also override the injector configuration for an app by invoking
* 2. It creates a new child injector (from the primordial injector) and configures the injector with the component's
* `services`. Optionally, you can also override the injector configuration for an app by invoking
* `bootstrap` with the `componentServiceBindings` argument.
* 3. It creates a new [Zone] and connects it to the angular application's change detection domain instance.
* 3. It creates a new [Zone] and connects it to the angular application's change detection domain instance.
* 4. It creates a shadow DOM on the selected component's host element and loads the template into it.
* 5. It instantiates the specified component.
* 6. Finally, Angular performs change detection to apply the initial data bindings for the application.
*
*
* ## Instantiating Multiple Applications on a Single Page
*
* There are two ways to do this.
*
*
* ### Isolated Applications
*
* Angular creates a new application each time that the `bootstrap()` method is invoked. When multiple applications
* are created for a page, Angular treats each application as independent within an isolated change detection and
* [Zone] domain. If you need to share data between applications, use the strategy described in the next
* section, "Applications That Share Change Detection."
*
*
*
* ## Instantiating Multiple Applications on a Single Page
*
* There are two ways to do this.
*
*
* ### Isolated Applications
*
* Angular creates a new application each time that the `bootstrap()` method is invoked. When multiple applications
* are created for a page, Angular treats each application as independent within an isolated change detection and
* [Zone] domain. If you need to share data between applications, use the strategy described in the next
* section, "Applications That Share Change Detection."
*
*
* ### Applications That Share Change Detection
*
* If you need to bootstrap multiple applications that share common data, the applications must share a common
*
* If you need to bootstrap multiple applications that share common data, the applications must share a common
* change detection and zone. To do that, create a meta-component that lists the application components in its template.
* By only invoking the bootstrap()` method once with the meta-component as its argument, you ensure that only a single
* change detection zone is created and therefore data can be shared across the applications.
*
*
*
*
* ## Primordial Injector
*
* When working within a browser window, there are many singleton resources: cookies, title, location, and others.
* Angular services that represent these resources must likewise be shared across all Angular applications that
*
* When working within a browser window, there are many singleton resources: cookies, title, location, and others.
* Angular services that represent these resources must likewise be shared across all Angular applications that
* occupy the same browser window. For this reason, Angular creates exactly one global primordial injector which stores
* all shared services, and each angular application injector has the primordial injector as its parent.
*
* Each application has its own private injector as well. When there are multiple applications on a page, Angular treats
* all shared services, and each angular application injector has the primordial injector as its parent.
*
* Each application has its own private injector as well. When there are multiple applications on a page, Angular treats
* each application injector's services as private to that application.
*
*
*
*
* # API
* - [appComponentType]: The root component which should act as the application. This is a reference to a [Type]
* which is annotated with `@Component(...)`.
* - [componentServiceBindings]: An additional set of bindings that can be added to the [Component.services] to
* - [componentServiceBindings]: An additional set of bindings that can be added to the [Component.services] to
* override default injection behavior.
* - [errorReporter]: `function(exception:any, stackTrace:string)` a default error reporter for unhandled exceptions.
*
*
* Returns the application`s private [Injector].
*
* @publicModule angular2/angular2
*/
export function bootstrap(appComponentType: Type,
componentServiceBindings: List<Binding>=null,
export function bootstrap(appComponentType: Type,
componentServiceBindings: List<Binding>=null,
errorReporter: Function=null): Promise<Injector> {
BrowserDomAdapter.makeCurrent();
var bootstrapProcess = PromiseWrapper.completer();

3
modules/angular2/src/core/compiler/binding_propagation_config.js vendored
View File

@ -1,5 +1,8 @@
import {ChangeDetector, CHECK_ONCE, DETACHED, CHECK_ALWAYS} from 'angular2/change_detection';
/**
* @publicModule angular2/angular2
*/
export class BindingPropagationConfig {
_cd:ChangeDetector;

2
modules/angular2/src/core/compiler/compiler.js vendored
View File

@ -21,6 +21,7 @@ import {CssProcessor} from './css_processor';
/**
* Cache that stores the ProtoView of the template of a component.
* Used to prevent duplicate work and resolve cyclic dependencies.
* @publicModule angular2/angular2
*/
export class CompilerCache {
_cache:Map;
@ -46,6 +47,7 @@ export class CompilerCache {
* The compiler loads and translates the html templates of components into
* nested ProtoViews. To decompose its functionality it uses
* the CompilePipeline and the CompileSteps.
* @publicModule angular2/angular2
*/
export class Compiler {
_reader: DirectiveMetadataReader;

3
modules/angular2/src/core/compiler/interfaces.js vendored
View File

@ -1,3 +1,6 @@
/**
* @publicModule angular2/angular2
*/
export class OnChange {
onChange(changes) {
throw "OnChange.onChange is not implemented";

1
modules/angular2/src/core/compiler/template_loader.js vendored
View File

@ -10,6 +10,7 @@ import {UrlResolver} from './url_resolver';
/**
* Strategy to load component templates.
* @publicModule angular2/angular2
*/
export class TemplateLoader {
_xhr: XHR;

13
modules/angular2/src/core/compiler/view.js vendored
View File

@ -28,6 +28,7 @@ var VIEW_POOL_PREFILL = 0;
/**
* Const of making objects: http://jsperf.com/instantiate-size-of-object
* @publicModule angular2/angular2
*/
@IMPLEMENTS(ChangeDispatcher)
export class View {
@ -280,6 +281,9 @@ export class View {
}
}
/**
* @publicModule angular2/angular2
*/
export class ProtoView {
element;
elementBinders:List<ElementBinder>;
@ -640,6 +644,9 @@ export class ProtoView {
}
}
/**
* @publicModule angular2/angular2
*/
export class ElementBindingMemento {
_elementIndex:int;
_setterName:string;
@ -656,6 +663,9 @@ export class ElementBindingMemento {
}
}
/**
* @publicModule angular2/angular2
*/
export class DirectiveBindingMemento {
_elementInjectorIndex:int;
_directiveIndex:int;
@ -712,6 +722,9 @@ class DirectiveMemento {
}
}
/**
* @publicModule angular2/angular2
*/
export class PropertyUpdate {
currentValue;
previousValue;

3
modules/angular2/src/core/compiler/view_container.js vendored
View File

@ -8,6 +8,9 @@ import {isPresent, isBlank} from 'angular2/src/facade/lang';
import {EventManager} from 'angular2/src/core/events/event_manager';
import * as ldModule from './shadow_dom_emulation/light_dom';
/**
* @publicModule angular2/angular2
*/
export class ViewContainer {
parentView: viewModule.View;
templateElement;

3
modules/angular2/src/core/dom/element.js vendored
View File

@ -1,6 +1,9 @@
import {DOM} from 'angular2/src/dom/dom_adapter';
import {normalizeBlank} from 'angular2/src/facade/lang';
/**
* @publicModule angular2/angular2
*/
export class NgElement {
domElement;
constructor(domElement) {