Add example of json use in json.rs

[musitdev]

I update the example of json use to the last update of the json.rs code. I delete the old branch.
From my last request, I remove the example3 because it doesn't compile. I don't understand why and I don't have the time now to investigate.

[musitdev]

Id add two function too
pub fn buffer_encode<T:Encodable<Encoder<'self>>>(to_encode_object: &T) -> ~[u8]
and
pub fn str_encode<T:Encodable<Encoder<'self>>>(to_encode_object: &T) -> ~str

[brson]

Those are some beautiful docs! (^0^)/

[musitdev]

I put ```rust isn't it right? Where are they missing? No problem to change but I thought it was ok.

[huonw]

@musitdev for inline code it is better if it is serialize::Encodable and #[deriving(Decodable, Encodable)], because then it will be rendered as serialize::Encodable rather than 'serialize::Encodable'.

[huonw]

boolean (`true` or `false`), number (`f64`), string, array, object, null.

[musitdev]

any chance that this request will be closed?

[emberian]

@musitdev you have yet to address @huonw's comment

[emberian]

See also the doctest changes at #11120; code examples in documentation should be executable.

[musitdev]

I've done the corrections but there are some code that is provided for the example and I don't put all the necessary use. I use the \rust,notest` tag to define the code. My problem is that the compiler still try to compile it and I have a lot of unresolved name error. Do I have to put the use which make the example less clear or is there any other tag.

[huonw]

Do I have to put the use which make the example less clear or is there any other tag.

You can prefix lines with a # to have those lines removed from the final output, but still passed to the test runner, e.g.:

# use extra::json::Json;

let j: Json = from_str("{}").unwrap();

Note that we will not want any code examples that aren't tested automatically (that is, no use of notest or equivalent at all), since they just bitrot and go out-of-date.

Also, we normally want the imports to be listed, to make the code examples self-contained (someone reading the docs for the first time won't necessarily know which functions to import and where to import them from), although if the imports are exactly the same in each one, it is possibly ok to only show the first one.

[musitdev]

It seems that I have a problem with the # directive that is use for struct annotation and hide comment.
the code
use extra::serialize::Decodable; #[deriving(Decodable)] pub struct MyStruct { attr1: u8, attr2: ~str, }
generate an error : expected one of;,}but foundpub`

If I add a space before the # I have the error :
failed to find an implementation of trait extra::serialize::Decodable<extra::json::Decoder> for main::MyStruct

Have you any idea?

[huonw]

That appears to be a bug in rustdoc; I'm just testing a patch for it now, I'll open a PR soon.

[huonw]

(Opened #11185)

[musitdev]

I've done a git fetch and git rebase and try make check and I still have the same problem. I push my change perhaps you can help me.

[huonw]

Oh, this is #4913. It should be fixed if you replace

#[deriving(...)]
struct Foo { ... }

bar();
baz();

with

#[deriving(...)]
struct Foo { ... }

fn main() {
   bar();
   baz();
}

(that is, give an explicit main, which stops rustdoc wrapping the entire example in its own main, which hits that issue).

[huonw]

It would be good to draw the json parsing and serialization comment into the start of this one, i.e.:

/*!
JSON parsing and serialization

# What is JSON?

JSON (JavaScript Object Notation) is ...

(Also, notice I have a space after the #, all the headings should have this.)

[huonw]

I personally don't like this example: I don't think we should necessarily be encouraging the use of ToJson, since serializing (using Encodable) directly to a string or a byte vector or any other writer will be much, much faster than going to JSON and then to a string.

[musitdev]

I put the ToJson example to show another possibility of serailization. And I said I think for the special case when you develope your own serialization code it's simplier.

[huonw]

Since this is documentation, I've been fairly picky about grammar and phrasing and also about code style in the examples.

[musitdev]

I understand your picky side for the docs. It's just you and I spend a lot of time to make this short toturial. At the beginning I thought it was simplier. Now I'am aware, I'll try to do it much better the next time. I'll update the code with your remarks.

[brson]

Thanks for your patience @musitdev

[musitdev]

The remark about ToJson still need to be settle.

[adrientetar]

Once you are done, it would be nice to have your commits squashed into one, something like:
git reset --hard HEAD~9 && git merge --squash HEAD@{1} && git commit (9 being the number of commits you want to merge)

[adrientetar]

s/by/be ?

[emberian]

@musitdev can you squash these commits? make sure to comment when you're done: github doesn't notify when a PR is changed.

[musitdev]

Done I squashed the last 10 commit. Tell me if it's ok.

[musitdev]

There was a change in the master. I update the file to compile. Does I have to redo a squash?

[huonw]

Yes please. Also, it'd be good if the squashed commit message was just something like "extra::json: add documentation and examples", rather than the list of the individual commits that were squashed.

[huonw]

The tests failed because MemWriter has moved to be just std::io::MemWriter rather than std::io::mem::MemWriter.

Comment when you've fixed it, for a new r+.

[musitdev]

I see it too late. I'll do the change, commit and squash

[emberian]

Yay! Congratulations :)

On Sun, Jan 19, 2014 at 10:41 PM, bors notifications@github.com wrote:

Merged #10801 #10801.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/10801
.

[olsonjeffery]

\o/ thanks so much for this @musitdev , this is great work

[musitdev]

Thanks it was a pleasure. Everybody has done a great job to make things better.