This means that we can now run just the d.ts file generation by running:
```bash
gulp docs/typings
```
In addition the type definition generation was messing with the other docs tasks
so separating it also fixes problems there.
This change prevents the doc generation from crashing due to a missing module,
but perhaps we need to think of a way of being able to generate the angular.d.ts
file correctly in `gulp public_docs`, perhaps by removing the need for
angular2/angular2.api
Previously, when a return type was missing it
could have been any. But following #2746 we
require return types so remaining untyped returns
must be void.
This removes some, but not all, of the manual work needed to patch up our
.d.ts for pushing to DefinitelyTyped. Remaining manual steps are:
- some types still missing
- declaration of decorators
- remove destructuring args
See #2686.
add test in gulpfile which will compile a basic TS file with generated
angular2.d.ts to ensure generated d.ts is valid syntactic TS
Adds support for enums in .d.ts generation pipeline.
Removes renaming reexports in http module.
At the moment we are not parsing param tags. This commit ignores them
completely.
TODO: hook up param descriptions with the actual param data in the doc.
Closes#2633
Previously, class members were ordered alphabetically.
This change leaves it up to the class author to
determine the order in which they would like
properties and methods to appear in class
documentation, without having to create methods like
`zUnimportantMethod`.
Fixes#2569
This requires some hacks, documented in
https://docs.google.com/document/d/1nNebWTiLzz5ePcit_bjZPtaiSIFU4EsQKUlX7LX0c0A/edit
Changes:
- include subtyping info in angular2.d.ts by adding 'extends supertype'
- export missing symbols needed transitively by angular2/angular2
- because of decorator/annotation mismatch, we can't export these to applications.
So I've added a separate angular2.api.ts file to re-export specifically to .d.ts
generation.
- Hack to remove aliases introduced by 'import * as alias' syntax
- Hack to deal with Error still an interface
note that we require users to install the transitive dependencies - this is how TSD works.
Previously this was a bit cryptic as we just had a `hideSpecialExports` flag.
Now it ignores exports that match an array of regexes, with the default case
being those exports called `___esModule`.
You can generate docs for comsumption by the angular.io website by running:
```bash
gulp docs/angular.io
```
The generated docs can be found in `dist/angular.io`
You can now write a link to a member of a class by appending the member name
to the class name joined by a hash sign:
```
{@link ControlGroupDirective#addDirective `addDirective`}
```
By default the link will contain the text of the class rather than the member
so you must add it as an inline code text snippet in the link tag.
Closes#1432
This commit enables links to other docs, such as classes and modules,
via the `{@link CodeIdentifier}` style inline tag.
Dgeni identifies what you are linking to by comparing the identifier to the
aliases for each doc. If no alias matches the identifier then the dgeni
run exits with a missing doc in link error. If more than one alias matches
the identifier then dgeni exits with an ambiguous link error.
In the future we could build in some heuristics for choosing a preferred
doc when the link is ambiguous, such as choosing a public doc over a
non-public doc; and choosing a code component that is in the same module as
the doc where the link is found.
Currently there are two aliases for each API component: its name and its
identier. For example, if the `Directive` class is exported from
`angular2/annotations`, so its aliases are 'Directive' and
`angular2/annotations.Directive`.
There is an issue in the non-public doc generation, which means that it
does not yet have `{@link}` tags implemented. This is that when we re-export
a code component, it gets cloned into another module. This means that a
simple reference to the code component's name will always produce an
ambiguous link. This can be fixed with a heuristic as described above.
Meanwhile you can avoid this by always using the full id of the code
component if it is being re-exported.
Closes#1371Closes#1421
chore(doc-gen): capture docs for modules from comments
Closes#1258
docs(*): add module description jsdoc tags
docs(*): add @public tag to public modules
chore(doc-gen): fix overview-dump template
The template was referencing an invalid property
chore(doc-gen): use `@exportedAs` and `@public` rather than `@publicModule`
This commit refactors how we describe components that are re-exported in another
module. For example the "public" modules like `angular/angular` and `angular/annotations`
are public but they only re-export components from "private" modules.
Previously, you must apply the `@publicModule` tag to a component that was to be
re-exported. Applying this tag caused the destination module to become public.
Now, you specify that a module is public by applying the `@public` tag and then
you can "re-export" components to other modules by applying the `@exportedAs`
giving the name of the module from which the component will be re-exported.
tag. This tag can be used multiple times on a single component, allowing the
component to be exported on multiple modules.
docs(*): rename `@publicModule` to `@exportedAs`
The `@publicModule` dgeni tag has been replaced by the `@exportedAs`
dgeni tag on components that are to be re-exported on another module.
Closes#1290
Now the visitor will find the last jsdoc style comment (e.g. `/** jsdoc comment */`)
before the current code item, ignoring any inline style comments (e.g. `// inline comment`)
in between.
Closes#1072
In the case that there were more than one comment blocks preceding a block of
code, the visitor was only attaching the first comment. Really what we
should do is to attach the last comment before the code block.