Support for flowtype Decalartions

[Davorak]

Here is an example of using a flowtype declaration to give a type annotation to a function:

/**
 * test function returns true
*/
declare var test : () => boolean;
function test(){
  return true;
}

The documentation produced does not capture the type annotation:

While if you use the syntax:

/**
 * test function returns true
*/
function test() : boolean {
  return true;
}

It produces the documentation which does capture the type annotation:

Unclear to me how realistic it is to support flowtype's various syntaxes for type annotation without using flow directly to parse the file however.

Let me know if this fits into the scope for this project/repo.

flowtype declaration doc: https://flowtype.org/docs/declarations.html

$ documentation --version
4.0.0-beta12

[arv]

We do use flow to parse the file.

It should not be too hard to recognize declare statements. Might be a good first bug?

[tmcw]

@Davorak yep, if you're interested in working on this issue:

• I'd much recommend trying astexplorer to see the parsed representation of the file
• It looks like findTarget would be the first place to look: we traverse the VariableDeclaration but we don't handle DeclareVariable, the kind of node that declare var yields.

[gajus]

A lack of Flow is support is a bummer. I have tried using documentationjs on a large project, but it gets polluted without countless of orphan declarations scattered across documentation. Is there at least a way to exclude them?

Example:

declare type AdRequestServiceConfigurationType = {|

  /**
   * @see https://developers.google.com/doubleclick-gpt/reference#googletag.defineSlot
   * @memberof AdRequestServiceConfigurationType
   */
  +adUnitPath: string,

  /**
   * @see https://developers.google.com/doubleclick-gpt/reference#googletag
   * @memberof AdRequestServiceConfigurationType
   */
  +googletag: GooglePublisherTagServiceType,

  /**
   * A collection of key, value pairs using to configure default targeting values.
   *
   * @see https://developers.google.com/doubleclick-gpt/reference#googletag.PubAdsService_setTargeting
   * @memberof AdRequestServiceConfigurationType
   */
  +targeting: TargetingParameterType,
  +slots: Array<AdRequestServiceSlotConfigurationType>
|};

adUnitPath will appear as an orphan in the documentation, with no context (it is not even even respecting the @memberof that I have added).

[tmcw]

Just to be clear to anyone who sees this ticket: we do support a lot of Flow syntax: we can infer the types of parameters and return types using Flow, and we transform flow declarations into JSDoc typeclasses. What we don't support, yet, is automatically adding declare statements to code, since documentationjs has for the most part avoided documenting anything automatically, so that authors can specify what they want documented, on the assumption that the public API of software is typically the minority of functions and code, with the rest encapsulated.

@gajus for now you can use /* instead of /** to skip processing or use @private to remove from the public API.

[Happy-Ferret]

Any support for this and .js.flow files in the pipeline? documentation is, unfortunately, not very useful to my workflow if it can't infer the type declarations (i e declare export function foo (msg :string) :void) inside an external declaration file (i e main.js.flow)

[tmcw]

In terms of 'my' pipeline, it's something I'd implement eventually but certainly not the top priority - bug fixes are the top priority for me at this point. If you'd like to see this happen sooner, I enthusiastically encourage you to try adding it and contributing a PR!