More fixes2

[IgorMinar]

No description provided.

[IgorMinar]

@petebacondarwin any idea why do the private entry points need to be blacklisted using extra _? the source code has a double underscore prefix, but dgeni somehow turns it into triple underscore.

[IgorMinar]

@naomiblack this PR also fixes the api listing json serialization.

unfortunately, the api docs still fail to build against the latest angular/angular master because some symbols are intentionally used twice with the same name (once in value position and the other time in the type position). it seems that dgeni doesn't like this duplication:

[00:23:49] 'build-ts-api-docs' errored after 4.94 s
[00:23:49] Error: Only one of "stable" (or its aliases) allowed. There were 2 - doc "@angular/core/index/Attribute" (interface)  - from file "/Users/iminar/Dev/angular/modules/@angular/core/src/metadata/di.ts"
    at readTags (/Users/iminar/Dev/angular.io/node_modules/dgeni-packages/jsdoc/processors/extract-tags.js:134:15)
    at /Users/iminar/Dev/angular.io/node_modules/dgeni-packages/jsdoc/processors/extract-tags.js:86:11
    at arrayEach (/Users/iminar/Dev/angular.io/node_modules/lodash/lodash.js:522:11)
    at Function.forEach (/Users/iminar/Dev/angular.io/node_modules/lodash/lodash.js:9011:14)
    at tagExtractor (/Users/iminar/Dev/angular.io/node_modules/dgeni-packages/jsdoc/processors/extract-tags.js:65:9)
    at /Users/iminar/Dev/angular.io/node_modules/dgeni-packages/jsdoc/processors/extract-tags.js:20:9
    at Array.forEach (native)
    at Object.$process (/Users/iminar/Dev/angular.io/node_modules/dgeni-packages/jsdoc/processors/extract-tags.js:18:12)
    at /Users/iminar/Dev/angular.io/node_modules/dgeni/lib/Dgeni.js:202:28
    at _fulfilled (/Users/iminar/Dev/angular.io/node_modules/q/q.js:834:54)
    at self.promiseDispatch.done (/Users/iminar/Dev/angular.io/node_modules/q/q.js:863:30)
    at Promise.promise.promiseDispatch (/Users/iminar/Dev/angular.io/node_modules/q/q.js:796:13)
    at /Users/iminar/Dev/angular.io/node_modules/q/q.js:857:14
    at runSingle (/Users/iminar/Dev/angular.io/node_modules/q/q.js:137:13)
    at flush (/Users/iminar/Dev/angular.io/node_modules/q/q.js:125:13)
    at _combinedTickCallback (internal/process/next_tick.js:67:7)

@petebacondarwin could we change dgeni to deal with this?

[petebacondarwin]

I'll take a look today.

Both seem a bit weird. The @stable problem is probably due to the TypeScript processor concatenating the two exports together in some way...

[IgorMinar]

thanks!

On Tue, Sep 13, 2016 at 12:32 AM Pete Bacon Darwin notifications@github.com
wrote:

I'll take a look today.

Both seem a bit weird. The @stable problem is probably due to the
TypeScript processor concatenating the two exports together in some way...

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#2321 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AANM6IfMbtHhahARgbfSDQh9mlQYmMhDks5qplGIgaJpZM4J7XTh
.

[petebacondarwin]

The trouble is that, as far as TypeScript is concerned, the following two declarations are the same symbol:

export interface Attribute { attributeName?: string; }
export const Attribute: AttributeDecorator =
    makeParamDecorator('Attribute', [['attributeName', undefined]]);

It is not clear how we should deal with this. Since TypeScript allows reopening of types, we assumed that multiple declarations for a symbol were for the same type and so we concatenate all the information from the two declarations into a single document, which is why the content field for this document looks like:

Type of the Attribute metadata.\n\n@stable\n\nAttribute decorator and metadata.\n\n@stable\n@Annotation\n\n

Thoughts:

• We could ignore one of the declarations, but which one?
• We create two documents but then they would have the same path and one would end up overwriting the other
• Moreover it seems that now that we have dropped the [Decorator]Metadata term, the current processing to extract decorator docs is going to be broken as it relied on the ...Metadata suffix to find the symbol that contained the information about the properties for the component.

[petebacondarwin]

Currently, on angular.io, the interface version of Attribute is lost anyway. The only doc rendered is https://angular.io/docs/ts/latest/api/core/index/Attribute-var.html

[Foxandxss]

In any case, we can't deploy the rc7 docs without fixing this.

[petebacondarwin]

I don't like doing the replacement here in the code.
We don't necessarily know at this point what the output rendering file format would be...
It is better to do the escaping in the template at /angular.io/tools/api-builder/angular.io-package/templates/api-list-data.template.html

[petebacondarwin]

Here is my fix for this: #2324

[IgorMinar]

yeah. I agree but I didn't know how to do it in a template :) I left a comment on your pr

[petebacondarwin]

OK, so here is thing: TypeScript allows "compatible" declarations to be merged into a single symbol. So interface and const can be merged. The resulting symbol has all the symbols of both types.

A type can have a valueDeclaration, which is the first declaration that is a "value" type, e.g. class, function, enum, const, etc, rather than a non-value, such as interface,typedef, etc.

Up to now we just concatenate the docs from each declaration into a single doc, which interestingly is what TypeScript does too - you can see so in the IDE intellisense.

I am going to update the dgeni-packages/typescript package to only take one of the declarations as the primary document, but then attach the other declarations to that doc via an additionalDeclarations property. This should prevent the doc-gen from blowing up and give us access to the other declarations.

The declaration that will be taken for the primary doc will be the valueDeclaration if there is one, or declarations[0] otherwise.