dart-lang
Produce a machine-readable format
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.
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.
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 :)
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?
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 https://github.com/dart-lang/dartdoc/issues/6#issuecomment-95655775.
Sent from my Motorola Startac
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 :frowning: .
We kind of do now... it's very very simple: index.json and it only supports search. Will leave this open for now.
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.
Producing a machine-readable json of the API surface of a dart package has come up again a few times recently.
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.
This issue seems obsolete. Not that we never need a machine-readable output, but rather the specific requirements are so unclear as to make this issue unactionable.
If you need something like this, please either add specific requirements to this issue, or simply open a new one.
