Update readme to match lib doc #48
Conversation
|
I think the README should provide a brief overview of the library and explanation of what it does, and for detailed usage information that's what the documentation is for. For this reason I'm inclined to say the README is fine as is. What do you think @frewsxcv? |
There was a problem hiding this comment.
Personally, I'm in favor of having the README be identical (or near-identical) to the top level module docs. There are a couple RFCs open related to this:
- Add API documentation front page styleguide rust-lang/rfcs#1687
- Add external doc attribute to rustc rust-lang/rfcs#1990
On the one hand, it's unfortunate having the duplication, but the second RFC should make it easier to reduce duplication by having the module level documentation just point at the README.md file. I do see why people might want to have minimal docs in the README and just point to the API documentation, but I just happen to prefer having a brief overview of the library in the README. What do you think?
| channel.validate().unwrap(); | ||
| ``` | ||
|
|
||
| ### Example |
There was a problem hiding this comment.
Instead of having two Example sections back to back, you could do something like this if you wanted:
### Examples
Validating a `<channel>`:
'''
<code here>
'''
Validating an `<image>`:
'''
<code here>
'''
|
I too prefer having the readme very similar to the crate top module documentation. |
|
Fair enough, that's good with me then. |
README.md
Outdated
| rss = { version = "*", features = ["from_url"] } | ||
| ``` | ||
|
|
||
| ```ignore |
There was a problem hiding this comment.
This should be ```rust,no_run
we we want the Rust syntax highlighting, but we don't want this test to run since it hits the network
https://doc.rust-lang.org/nightly/book/first-edition/documentation.html#running-documentation-tests
There was a problem hiding this comment.
though, since these code blocks aren't being tested (since they're in the README), it actually doesn't matter if we no_run or ignore, so yeah, just rust should be fine
README.md
Outdated
|
|
||
| ### Example | ||
|
|
||
| ``` |
README.md
Outdated
|
|
||
| ### Example | ||
|
|
||
| ``` |
README.md
Outdated
|
|
||
| ### Example | ||
|
|
||
| ``` |
There was a problem hiding this comment.
This should be ```rust as well
|
This is great, thanks! |
No description provided.