--json docs + Readme

[Dajamante]

• completed documentation (v0.3.3+ is necessary to use the --json flag)
• example of json output with formatter
• small link broken in the readme

[japaric]

thanks. I left some suggestions.

[japaric]

I think we should say that the main goal of --json is to produce machine readable output. one of the use cases for that is changing the human-readable format

[japaric]

I think this questions overlaps with the one that says "what can I do with the JSON output?". I would suggest simply mentioning that one use case is changing the human readable output and the piped command. jq without any flags is not a good example of human readable output, maybe change it to only show the data field?

[Dajamante]

I can also remove the whole reference to jq, as it is not relevant information here.

[japaric]

Not part of this PR but could you fix this line; it has a missing link:

To do that, we supply a few things in [defmt_json_schema]:

[japaric]

I would suggest moving this addition to the very end and mention that jq is an existing tool that can be used to change the output format. But again, the example output should be be JSON but something more readable.

[Dajamante]

Do you mean what is above, or what is under?

{
  "data": "I am a PRINTLN-statement",
  "host_timestamp": 1647942992494142200,
  "level": null,
  "location": {
    //...
    }
  },
}

[japaric]

But again, the example output should be be JSON but something more readable.

should not be JSON.

by "example output" I meant the code block. Ideally, it should be something like

$ cargo r --example foo | jq "something here"
I am a PRINTLN-statement
the next log statement

[Dajamante]

I would suggest moving this addition to the very end and mention that jq is an existing tool that can be used to change the output format. But again, the example output should be be JSON but something more readable.

Dumb question, do you mean at the very end of the page or the very end of the paragraph? I fear it will be a bit out of context at the very end of the page.

[japaric]

I meant at the end of the page. After re-reading the page I think a good place may be after the first paragraph of the "Data transfer objects"

So, what can I do with the JSON output?
There really are no boundaries. (..)
(NEW) One option is to use a program like jq to extract the parts of interest. blah blah show console example
If you wish to deserialize (..)

[Dajamante]

Maybe that sentence is enough ⬆️ . Everybody already saw a json output. The console example does not bring anything.

[japaric]

ok, the sentence can be enough but I guess it should say "pipe to a program like jq" instead of "use"

[Dajamante]

To do that, we supply a few things in [defmt_json_schema]:

I don't think the link is very informative...
https://crates.io/crates/defmt-json-schema

I will remove the linking instead, since Johann wrote extensive information.

[japaric]

I don't think the link is very informative...

I think the link still helps because you can tell it's a crate and what version it's available.

[japaric]

thanks!
bors r+

[bors]

Build succeeded:

• ci