-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
turned code samples into proper Rust tests
- Loading branch information
Showing
1 changed file
with
166 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
3e1a9e7
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
First of all, thank you for doing this.
I can say I don't really like it when there's a lot of explanatory text like this (I find it hard to find the real code). I'd much rather see it in a separate module somehow (not sure if that's possible--just stating a preference); also by having it here and in README.md, the docs are no longer DRY.
I do like the idea of the examples being compiled for validity, though.
LMK if you have any thoughts on the concerns...
3e1a9e7
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
3e1a9e7
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Re: 1: I'm agreed that all our published crates should have proper documentation. It's not clear to me at all that the documentation needs to be in Rust format.
Can you tell me more about your experiences with crates with no docs other than the GitHub README.md? Why did those experiences suck?
FYI, I now wish I'd saved it--but here's a counter-data-point: a Rust community member (sarnold) was very complimentary to me about the docs on IRC yesterday. He found them easy to digest and complete. He even took time to highlight a number of points in the docs that he liked. No mention of issues with it not being Rust documentation. I was not soliciting documentation feedback.
Just so I'm clear, I'm not against it being Rust documentation per se. But I am against 1) duplication and 2) making the source code harder to read.
Re: 2: agreed--very little tractions
Re: 3(ii) too bad this doesn't resolve the DRY problem...
Re: 4: even though it's a temporary measure, I think we're years away from a true cargo solution--there are too many other fish to fry in the Rust ecosystem. I'll play with this a bit, and if it can reliably do the basics, I think it could be what we need.
Thank you for all the suggestions on how to improve this situation. Very cool. :)
3e1a9e7
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
3e1a9e7
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes. I've been though them both multiple times.
If I'm understanding correctly, what was actually frustrating for you was not that the docs were in a README.md, but that the docs were out of date. And you are (rightfully) concerned about maintaining synchronization in our codebases as well.
That is the point we should be focused on. (eg. what if we or someone else built a script that included the README.md as part of the docs compilation process? If that's the shortest path to ensuring a synchronized, valid, DRY API, then that should be on the table. I think the README.md is more a symptom, rather than a root cause.)
Ah, since you brought this up in the Assayer publish PR, I've been under the impression you were referring to Assayer this whole time. Certainly, a more complex library or framework would want to revisit this and yes, I'd want us to do what was appropriate. I agree that documenting, say, Rocket in a README.md is probably not the wisest course of action... ;)