Alternative readme API doc style

[jamestalmage]

Thinking outside the box for a minute, what if our docs was just a Flow declaration:

---

getStream(stream, ?options)

getStream(
  stream: ReadableStream, 
  ?options: {
    maxBuffer: number = Infinity,
    encoding: string = 'utf8'
  }
);

---

It communicates a lot very quickly.

The only problem with using code blocks is that it doesn't split the document up and provide link anchors, so you still need a header line. That creates some duplication.

[sindresorhus]

I like it. The downside, as you said, is that the description is decoupled from the definition.

Some other examples that I encountered today:

• https://github.com/thgreasi/localForage-observable#api
• https://github.com/zerkalica/modern-router#interfaces

[SamVerschueren]

If we would write our modules with TypeScript, this information is automatically available to us :). Example for camelcase. I'm not suggesting that we shoul do that though, just throwing it in the ring ;).

If we would go for something like this, I'd suggest using the TypeScript definition system (which looks quite a lot like Flow). I believe TypeScript will become more popular due to Angular 2.

[jamestalmage]

What would the getStream docs above look like with TypeScript?

I would pick whichever one seems the easiest to understand without any experience with that particular language extension.

I am not sure what writing in TypeScript gets us in the way of documentation. We would still need to extract definitions from actual code for the docs.

[SamVerschueren]

The only difference I noticed thus far between Flow and TypeScript is the indication of an optional argument.

getStream(
  stream: ReadableStream, 
  options?: {
    maxBuffer: number = Infinity,
    encoding: string = 'utf8'
  }
);