Document the public API

Right now when writing dangerfiles, I reference the TypeScript interfaces within the codebase. It would be helpful to bring the public API out into the open somehow.

The reason I bring this up is because I’m introducing Danger-js into some codebases at work and want people to get involved, but it becomes a bit more challenging when the API documentation is within the codebase and spans multiple files.

Would it make sense to maintain an index.d.ts file like Redux does that could also be used to generate a simple API documentation website or something like that?

I wanted to get a conversation started on this to see what some plans are down the line and what I can help with in the near future. 👍

Sidenote: how will danger-js be integrated into the Danger website reference when it hits 1.0? Is there a way we can consider documenting this codebase’s API in a way that would more easily integrate into the official website down the road?

[kwonoj]

Would it make sense to maintain an index.d.ts file like Redux does that could also be used to generate a simple API documentation website or something like that?

: I’d actually object with that, it isn’t generally recommended idea to have ambient declaration while source code is TypeScript already with shipping its definition. Probably what we need is documentation pipeline like typedoc (http://typedoc.org/) / tsdoc(http://myaut.github.io/tsload/devel/tsdoc.html)

Say we shipped a danger.d.ts file alongside the flow type definition, would that require a user to write a dangerfile in TypeScript (dangerfile.ts)?

: no, type definition is always opt-in. I’m currently having dangerfile written in js. moreover, if user write dangerfile in typescript. as @orta mentioned, VS code has first-class support for typescript so even you’re writing js, it can pull down dependency’s type definition to provide corresponding language services though.

[orta]

We do ship docs in the form of flow type annotations inside NPM releases -> https://github.com/danger/danger-js/blob/master/scripts/create-flow-typed-export.js

See it in action here: https://twitter.com/orta/status/793861861930401792 This will need porting to TS at some point though.

And yeah, won’t be 1.0ing until there’s a website with real docs, and all docs need to be generated from source.