Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation for core::io. #5673

Closed
wants to merge 2 commits into from

Conversation

steveklabnik
Copy link
Member

When I submitted #5659, it apparently caused some test failures. Then, because I left it in my incoming rather than making a new branch, I deleted my commit.

Let's try this again, this time, with its own branch so that I don't screw it up.

r?

@sanxiyn
Copy link
Member

sanxiyn commented Apr 2, 2013

  • If examples are "none right now", I think they should be removed.
  • Documentation of SeekSet seems strange to me. What is "the new position"? I think SeekSet means you seek from the beginning.

@steveklabnik
Copy link
Member Author

  1. I left them in so that they're easier to add in an identical format later, but if everyone feels differently I can remove them. @brson gave me a + before with them in.
  2. SeekSet is used in the context of seek, which sets a new position in the stream. That said, if it's not clear, it can get better. "you seek from the beginning" is exactly right, but then why's it called 'set' instead of 'beginning?' I tried to make the explanation similar to the name of the option.

@thestinger
Copy link
Contributor

I think the sections for examples should be left out until there are actually examples - I don't think we'll ever end up adding examples for every single function.

@steveklabnik
Copy link
Member Author

I don't think we'll ever end up adding examples for every single function.

I plan on doing it. It's going to take a while, but good examples are the difference between good docs and amazing docs.

@findow
Copy link

findow commented Apr 2, 2013

I think that there wouldn't be any need for examples if there was the ability to reference test functions: there are test functions for each function and they essentially show how to use them, what is the output and when they fail.
It would be better if it could be possible to say "Examples: see test_foobar": maybe something could be done to rust_doc, but making examples when there are test functions is redundant IMHO.
@brson ?

@thestinger
Copy link
Contributor

Examples written with the intent of documenting the functions are going to be much better than code written to test them. I just don't like the placeholders.

@steveklabnik
Copy link
Member Author

This should fix the build error.

bors added a commit that referenced this pull request Apr 3, 2013
When I submitted #5659, it apparently caused some test failures. Then, because I left it in my incoming rather than making a new branch, I deleted my commit.

Let's try this again, this time, with its own branch so that I don't screw it up.

r?
@bors bors closed this Apr 3, 2013
@steveklabnik steveklabnik deleted the improve_io_docs branch October 25, 2017 18:24
tesuji pushed a commit to tesuji/rustc that referenced this pull request Jun 4, 2020
Add regression test for endless loop / update `pulldown_cmark`

Closes rust-lang#4917

This was fixed in pulldown_cmark 0.7.1, specifically pulldown-cmark/pulldown-cmark#438

changelog: none
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants