search

rust-unofficial / patterns

A catalogue of Rust design patterns, anti-patterns and idioms
https://rust-unofficial.github.io/patterns/
Mozilla Public License 2.0
8.11k stars 375 forks source link

Fixing code examples, statement about working tests on code examples #51

Closed llogiq closed 3 years ago

llogiq commented 7 years ago

This doctests all code examples. There is some fallout to either ignore examples (if I deemed them too far from runnable) or change them to work, or at least compile.

I also added a .travis.yml so we can use CI to check PRs.

fixes #49

nrc commented 7 years ago

Hmm, I wonder how worthwhile this is - it found one bug (which is nice), but I feel like every example which gets changed has got more cluttered and less easily understandable and that doesn't feel like a great trade-off to me.

lambda-fairy commented 7 years ago

Rustdoc lets you hide setup code by prefixing it with #, but I'm not sure how that'll help in our case.

llogiq commented 7 years ago

I see two ways going forward:

Perhaps we can even do both and have the script build the examples?

lambda-fairy commented 7 years ago

See also #6 and #44. It would be nice to publish this to a standalone website one day.

Having a separate examples directory doesn't feel right, somehow. I think it's because the examples are so short that splitting them out into separate files won't be worth the extra effort. Maintaining a separate set of examples may raise the barrier to entry for contributors as well.

Also, since rustbook is built on top of rustdoc, I think it'll strip # lines already.

llogiq commented 7 years ago

The idea is to have playground links. I'm not sure if this requires a canonical location per example or if the code gets embedded as link data.

lambda-fairy commented 7 years ago

Okay, I see what you're aiming for with the playground.

As prior art, the official Rust book has playground links -- e.g. see the section on lifetimes. It looks like they use the # prefix solution, displaying the pretty code in the book but linking to the full code on the playground.

Unless there are further issues with their approach, I'm keen to just copy what they do.

llogiq commented 7 years ago

Agreed. I'll look into that. Perhaps I should pare down this PR to the one fix I found then.

pickfire commented 4 years ago

Ping

simonsan commented 3 years ago

Small feedback (imho): I think it would be better at this stage to use Github Actions for that instead of Travis.

See next comment.

lambda-fairy commented 3 years ago

mdbook has a built-in doctest feature as well, which would make this PR redundant.

https://rust-lang.github.io/mdBook/cli/test.html

simonsan commented 3 years ago

mdbook has a built-in doctest feature as well, which would make this PR redundant.

https://rust-lang.github.io/mdBook/cli/test.html

Thanks for the heads-up, indeed, that looks like it would make it redundant when we convert this into a mdbook.

ref.: #6

simonsan commented 3 years ago

Seems good to me, @MarcoIeni any additions?

simonsan commented 3 years ago

Hey @llogiq is there any reason you're closing this? There are still changes to be merged from your PR that are not the concerning the doctests or Travis, I already edited your branch to remove the parts and changed the title.

simonsan commented 3 years ago

Added the statement of working code examples to the template.md in #123 . What about the additions to the examples and rust, ignore? Do we still want to merge that from this PR?

Added them in #124