Documentation format

[lbradstreet]

At the risk of slowing down contributions, would it be worth documenting these errors in edn/cljc, and then generating documentation from them? This would allow better tooling to be built around the errors.

I guess the risk is that errors aren't improved in clojure.core upstream since it might be seen as solved by tooling, which I think is the wrong approach overall.

[yogthos]

I think this could be useful as a future goal. Alex Miller is already working on improving the compiler error messages and they're a target for the next release. If anything I think this could help identify the errors people commonly stumble on and make sure those are improved.

[lbradstreet]

I agree overall. It was just a thought. Thanks! Much needed work.

On 26 Apr 2016, at 6:53 PM, Dmitri Sotnikov notifications@github.com wrote:

I think this could be useful as a future goal. Alex Miller is already working on improving the compiler error messages and they're a target for the next release. If anything I think this could help identify the errors people commonly stumble on and make sure those are improved.

— You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub

[tolitius]

@lbradstreet great idea. a problem could be lower contribution rate. i.e. much easier to throw an .md together. But I guess if we do something like:

{:error ""
 :cause ""
 :solutions ["" "" ...]}

it could work.

It is not immediately obvious how to format solutions and cause though, since .md is much simpler than DSLing it with EDN.

Do you have a format in mind? That would be both:

• rich enough not to miss any helpful details
• very friendly and approachable by beginners

[shaunlebron]

I'm not sure if there is enough data in our current reports for tools to figure out when to show it. But we could use a library like kidif with the option delimiter:"##" to compile this:

# Title

## Error
error

## Cause
cause

## Solution
solution 1

## Solution
solution 2

into this:

{"Error": "error",
 "Cause": "cause",
 "Solution": ["solution1", "solution2"]}

edn/json is just a non-starter as an input format for documents that are mostly literal text (escaping is not fun). Examples of us avoiding it recently: Parinfer compiles code blocks from this md to this json. cljs-api-docs compiles text files like this into the massive cljs-api-docs.edn file after merging with parsed symbol data.

[tolitius]

yep, agreed. edn could definitely impact contribution rate for various reasons.

.md with clear naming rules for headers can be easily parsed into edn to feed the err catalog DB.

one correction: I would name solutions. it may not seem important right now, but would help great deal with contextual searches and such.

added Error file format