Better flow type support for complex types

[philippotto]

As far as I can see the current flow type support doesn't support the use of the actual type definition.

For example:

/**
 * A ComplexType with some properties
 */
export type ComplexType = {
  a: number,
  b: number,
};

only outputs:

However, I would expect that the documentation also lists the properties of the type, since I don't want to mirror the definitions in the comments.

Are there any plans for that, or a workaround I could use?

[tmcw]

Hi Philipp!

With this input on current master, beta.19, and rc.0, I get the documentation:

documentation.js build -f html foo.js -o /tmp/out

Could you try upgrading to [email protected]?

Thanks! - Tom

[andrewcharnley]

I've a similar problem in that it doesn't pick up the comments for these properties (rc.1):

/**
 * Messagebus Interface
 */
interface fInterface {

  /**
   * Will virtually close the connection and prevent messaging
   */
  end(): undefined,

  /**
   * A virtual start to ensure messages don't trigger actions before ready
   */
  start(): undefined,

outputs:

## fInterface

Messagebus Interface

**Properties**

-   `end` **function (): [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** 
-   `start` **function (): [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** 
-   `send` **function ([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)): [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** 
-   `on` **function (event: [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), action: [Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)): [Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 

## end

Will virtually close the connection and prevent messaging

## start

A virtual start to ensure messages don't trigger actions before ready

[andrewcharnley]

These are at the correct level if I use @memberof on the children

[andrewcharnley]

Same on a type...

/**
 * Further config available to this module
 */
type extfConfig = fConfig & {

  /**
   * An AWS config file containing region etc. Loaded relative to home dir
   */
  configFile: string,

  /**
   * Device credential files from AWS IoT manager. Loaded relative to home dir
   */
  credentials: {
    privateKey: string,
    certPem: string,
    caCrt: string
  }
};

[TxHawks]

@andrewcharnley - Can you post an example of how you handled it with @memberof? Seems to have no effect at all when I do:

/** General description */
interface SomeInterface {
  /**
   * @memberof SomeInterface
   * Prop description
   */
  prop1: string;
}

Made a tiny reproduction repo: https://github.com/TxHawks/documentation-flow-repro The generated docs are available at https://TxHawks.github.io/documentation-flow-repro/

[jfirebaugh]

I put some work into this (pushed in https://github.com/documentationjs/documentation/compare/flow-memberof-inference), but it's incomplete and I ended up switching the code I was trying to document from a flow object type alias to a regular class anyway.

It's incomplete because in some cases it produces output that documents the same thing both as a member and as a JSDoc "property". Which now makes it clear to me that this is another deficiency in the JSDoc object model: "properties" are just another kind of member, and documentationjs should be normalizing @property to members, rather than having a separate collection.

[gre]

@jfirebaugh that sounds promising. do you have plan to submit a PR ?

[jfirebaugh]

No plans (I wound up not needing this), but I welcome anyone to pick up the work.

[carocad]

@jfirebaugh I could try to take a look at this if you can provide me some guidance on how to tackle it.

[jfirebaugh]

Hey, sorry, it's been a while and I don't remember much beyond what's in my comment above.

[punksta]

When class implements interface documentation could use types from the interface.

[devongovett]

I have changed interfaces to use members instead of properties in my TypeScript PR (but also for flow). See https://github.com/documentationjs/documentation/pull/1234/commits/28392f1801bd8ad4f0f520ac50878f6bbd42fd0d. This allows interfaces to work more like classes, and support annotations for method members, etc. whereas properties were quite limited.

I left type aliases the same (as records with properties), and that seems to make sense to me since interfaces are more often used to describe a class whereas types are more similar to type definitions and might be inlined into docs (e.g. as parameter types). I could be convinced to just make everything a member and not infer properties though. Thoughts?