Produce a machine-readable format

[sethladd]

Producing a file that is machine readable (such as a JSON file) helps enable mashups and unforeseen applications. For example, Dart's current docgen tool output JSON, and that lead to an API diff tool and an API score tool.

[sethladd]

Check with @srawlins as he is the consumer of the API docs JSON feed. He has two really nice tools that use this feature.

I think we'll need to continue to product the JSON output, as a separate Generator.

[srawlins]

Yeah I'm all in favor of keeping a machine-readable format (particularly the current JSON one :) ). Shapeshift uses it to compare two different JSON blobs representing two releases of the same API.

Also Doc Coverage (in the same repo as Shapeshift) uses it to score a package's documentation coverage. This tool relies on these JSONs being available over HTTP, which we can hopefully keep :)

[azenla]

I'll let @keertip take this, and I'll do the markdown generator.

[sethladd]

Help wanted on this one.

[srawlins]

As dartdoc parses Dart files, does it build a full tree of the API (public classes, public methods, etc.) before outputting to... HTML/Markdown? Or does it output as it goes?

[sethladd]

It builds a full tree.

On Thursday, April 23, 2015, Sam Rawlins [email protected] wrote:

As dartdoc parses Dart files, does it build a full tree of the API (public
classes, public methods, etc.) before outputting to... HTML/Markdown? Or
does it output as it goes?

—
Reply to this email directly or view it on GitHub
#6 (comment).

Sent from my Motorola Startac

[srawlins]

Just so I don't mislead anyone: I'm going on vacation through the end of June, so I'm not going to be able to help on this one at least until July 😦 .

[sethladd]

We kind of do now... it's very very simple: index.json and it only supports search. Will leave this open for now.

[sethladd]

We're not likely to take proactive action on this, unless driven by specific requirements. We do produce an index.json now. Please do open new issues for new info that you'd like to see in that file.

[jcollins-g]

Producing a machine-readable json of the API surface of a dart package has come up again a few times recently.

[jcollins-g]

FYI: index.json doesn't quite cut it -- it was already not exactly what people wanted, but it's particularly not what we need now. Post canonicalization, it doesn't include the complete API surface area.