fix(typescript): handle property accessors correctly

[petebacondarwin]

Closes #246

[devversion]

This doesn't seem to work properly. Right now if it's a combination of both getter and setter, then only the type of the getter will be used.

But actually it should try to find the type in the setter if it couldn't find a type in the getter. Thoughts?

[petebacondarwin]

What does it mean to have a getter that has no type? Oh, I guess that if you code has no explicit return type... e.g.

class C {
  _foo: string;
  get foo() { return this._foo; }
  set foo(value: string) { this._foo = value; }
}

Is that the scenario? Generally in our public API docs we always give getters a return type.
In that case, then I guess we do need to look at the setter.

[petebacondarwin]

I've added a commit that fixes this... @devversion PTAL

[petebacondarwin]

If we have passed in declaration or getAccessorDeclaration then we will have extracted the type from one of those, if possible.

[devversion]

Yeah that's true. On Material we have a small workaround for this, but it still uses the declaration to retrieve the type. See here

[devversion]

Might be worth to also check how the description of the getter/setter is being handled. I noticed that the description is only being read from one place.

get test() {}

/** Description on the setter */
set test(val: boolean) {}

[petebacondarwin]

So the getter and setter are docs in their own right, so their documentation should be processed for jsdoc tags, etc. You can then access them via the member.getAccessor and member.setAccessor for use in the property template.

This is similar to how overloads are being dealt with. With overloads we extract the content of the "actual" function for the member doc but then attach the content for each of the overload declarations to the overloads for that member.

In the case of a property with a getter and setter, we extract the content from the first declaration that is defined from [declaration, getter, setter]. It would seem to me more common to put the documentation (if there is only one) on the getter not the setter YMMV. But if you do put it only on the setter then you could easily get around this by doing something like:

Something like:

<h2 class="property-name">{$ member.name $}</h2>
<p class="description">{$ member.content or member.setAccessor and member.getAccessor.content $}</p>

Is this too unreasonable? Do you really put documentation on the setter only?

[devversion]

Not really, on Material I remember seeing accessors that have the descriptions on a setter or on the getter and I want to make sure we don't need to enforce something here.

For the description, for me it makes sense to have a description property on the "MemberDoc". The description there should be retrieved in a similar way as the type, because it can be either on the getter or setter.

// In theory the accessor should only have one JSDoc at all, 
// it's still considered a property.
memberDoc.description // Should show the proper description of the getter/setter.

[petebacondarwin]

OK, I'll transfer that from the relevant accessor too.

[petebacondarwin]

Done PTAL

[devversion]

Just tested it locally and the types seem to work fine now. For the descriptions, I'm not sure what's different to content is? When debugging most of our accessors in Material, they don't seem to have a content either.

Isn't there a way to set the description as well, based on the two cases I described above?

    // This works fine now. Seems like every thing has a type now!
    if (!propertyDoc.type) {
      console.log('No type for', propertyDoc.name);
    }

    // Likely every accessor doesn't have a description. 
    // "content" seems to be empty in most of the cases too.
    if (!propertyDoc.description) {
      console.log('No description for', propertyDoc.name, propertyDoc.content);
    }

This is the code-snippet we currently use in Material to receive the proper description for an accessor.

https://github.com/angular/material2/blob/4d97271786855598cfd18921641d5ffaafa079d8/tools/dgeni/common/dgeni-accessors-parse.ts#L51-L54

[petebacondarwin]

Remember that this processor runs before the jsdic processing happens. The content field contains the raw content. After jsdoc runs there will be a description property too

[devversion]

Hmm I'm not sure why the content is empty then. For me likely every accessor document has a content that is empty. Discussed on Slack.

[devversion]

LGTM. Thanks for the perfect work.